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C has become one of the most frequently used computer languages. The first C 
language was developed by Dennis Ritchieat Bell Laboratories in 1972 and ran on a 
DEC PDP-11. The AN SI standard forC, which replaced the standard written by 
Kernighan and Ritchie in 1978, is only a few years old. 

C's structure is similar to PL/I (a popular language used on IBM 's mainframe 
computers), FORTRAN, Pascal, and BASIC. C is a simple language. It has only a 
small group of keywords and no support for I/O or advanced math. The power 
of C comes from its simplicity and its use of a standard library of functions. 



Advanced C isfortheprogrammer who has some experience writing applications in C 
or a similar language, such as PL/I or Pascal. Regardless of whether you are an 
intermediateor experienced programmer, thisbook isintended to improveyour skills 
as easily as possible. 



This book has several purposes. First, it introduces advanced parts of theC language. 
1 1 also describeschangesin theAN SI standard, which istheonly truedefinition of the 
C language. In addition, the book contains much of what I have learned (often the 
hard way) about C programming. 

Advanced C is divided into five parts, and each part can be used by itself. Part I 
gets you started and I ays the ground work for the rest of the book. In Part 1 1, you learn 
how to managedataand files when programming in C . Part 1 1 1 introducesintegrating 
C with other languages and interfacing with other environments such as database 
programs. Part IV is a reference section that covers the header files, the intrinsic 
functions, thepreprocessor, and someperformanceand debugging techniques. Part V 
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(the appendixes) contains an ASCII table, information about different compilers, an 
introduction to C++, and a cross-reference of functions and their header files. 

M any chapters contain example programs. In some chapters, a single example 
program is used to demonstrate several topics in the chapter. 

For a platform to develop C software, I recommend at least a 386/25, and 
preferably a 386/33 or 486. A 286 will do, but most linkers and some compilers are 
noticeably slower when you do not havea fast CPU. I suggest that you haveatleasta 
100M hard disk. The compiler I use most frequently is QuickC for Windows. It is 
powerful and easy to use (because it has an integrated debugging environment), and 
supports both ANSI C and M icrosoft's extensions. 

Conventions Used in This Book 

I used thefollowing conventions in the book: 

• All program listings and code fragments are in monospace. 

• All function namesarein monospace. 

• ANSI C keywordsarein monospace. 

• All function names appearing in text (not in the code) are followed by an 
empty set of parentheses, for example, spr i nt f ( ) . 

• Something that must be substituted (such as a filename or a value) is in 

mo n o s p a c e italic. 

• When a listing title shows a filename in uppercase, that file is usually found on 
the sample diskette. If a filename is not given or it isin lowercase, then it isnot 
a separate source file on the diskette, but probably part of another fileon the 
sample diskette. The text usually indicates which file the code fragment is 
from. 



A N ote on Practicing C 

You can read, attend lectures, or discuss a subject, but as the saying goes, "practice 
makes perfect." 
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Do not be afraid to practice with the programs in this book. But practice does 
not mean copying a program from thediskette, compiling it, and running it. C hange 
the example programs. M akethem do things they weren't intended to do and learn 
from your mistakes. M ake backups often and program away. BecauseC isapowerful 
language and many of us are programming on PCsusing DOS (which has very poor 
memory protection), be careful; it is easy to trash the disk. 

Good luck improving your C programming skills, have fun writing your software, 
and remember Peter's rule: Back up your disk frequently! 
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TheC Philosophy 

C probably wasn't your first computer language. M ine was FO RTRAN , and many 
other people began their study of computer language with either BASIC or PASCAL. 
No matter which language was your first, you probably will spend much time 
programming in C from now on. T hischapter coversa number of introductory topics. 



A Brief History of C and the Standard 

U ntil the past few years, no absolute standard for the C language existed. The C 
Programming Language, by Kernighan and Ritchie, served as a standard, but most 
compiler manufacturers added extensions and did not follow all the specifications 
presented by Kernighan and Ritchie. AsC becameoneof themost popular computer 
languages for programming small computers, the need for a true standard became 
apparent. 
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The American National Standards Institute (AN SI) produced standards that 
help keep each of thecompilersworking in thesamemanner. These standards, which 
are very exacting, spell out exactly what the language should do and what should not 
happen. Specified limits and definitions exist also. 

C is an interesting language. Because its syntax is simple, it's not the most 
powerful language, and it has only a few operations. M ost of C 's power comes from 
these attributes: 

• C can address and manipulate memory by direct address A program can obtain 
the memory address of any object (both data objects and functions) and 
manipulate without restriction the contents of the memory specified by the 
address. This capability is good to have because it allows flexibility. However, 
you have no protection from the program overwriting critical parts of the 
operating system when you are programming a PC using DOS. 

• C hasa powerful library of functions This library of functions enables program- 
mers to perform I/O, work with strings (which are arrays of characters), and 
perform many other tasks. 

There is a lot of talk (much I consider to be blown out of proportion) about 
portability. Generally, for each program, you should consider whether it is likely to be 
needed on a different system, and how much effort must bededicated to planning the 
movetoafuturesystem.SomeC programming isnever portable. Programswrittenfor 
M icrosoft Windows, for example, don't move well to the Apple M acintosh or IBM 's 
0 S/2 Presentation M anager (a system much likeW indows). T hedecision to maintain 
portability isonethat you must make— sometimes the effort to maintain portability 
far exceeds what is required if later parts of the program must be rewritten. 

TheAN SI standard specified anumber of languagelimits(seeTablel.l). M any 
of theselimitsarereally compiler limits; however, becausethey affect the language, you 
sometimes must takethem into consideration. Theselimitsarenot usually a problem; 
in theten years that I've been writing C programs, I've run into problems with these 
limits only once or twice. 
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Data Types, Constants, 
Variables, and Arrays 

The C language offers a number of data types, which can be used for constants, 
variables, and arrays. This chapter helps you become more familiar with data objects 
and how to use them. 



Data Types 

TheC language supports a number of datatypes, all of which are necessary in writing 
programs. Because most CPUs generally support these data types directly, it is 
unnecessary for the compiler to convert the data types into the types the CPU 
understands. In addition to the standard types, new data types are needed, which are 
often uniquetoagiven application, and C provides themechanismsto create and use 
types of data created by the programmer. 
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Thebasic data types as they aredefined by theAN SI standard arelisted in Table 
2.1. They are all that are needed when simpler applications are created (and are 
generally ad equate for many of the more complex programs). 



Table 2.1. C'sdata types. 



Type 


Size 


Description 


char 


1 byte 


U sed for characters or integer variables. 


i nt 


2 or 4 bytes 


Used for integer values. 


float 


4 bytes 


Floating-point numbers. 


do u b 1 e 


8 bytes 


Floating-point numbers. 



In addition to these data types, someof them maybeused with a modifier that affects 
the characteristics of the data object. These modifiers are listed in Table 2.2. 



Table 2.2. C'sdata type modifiers. 
Modifier Description 

long Forces a type i nt to be 4 bytes (32 bits) long and forces a type 

double to be larger than a d o u b i e (but the actual size is imple- 
mentation defined). Cannot be used with short . 

short Forces a type i nt to be 2 bytes (16 bits) long. Cannot be used 

With long. 

unsigned C auses the compiler (and CPU) to treat the number as con- 
taining only positive values. Because a 16-bit signed integer can 
hold values between -32,768 and 32,767, an unsigned integer 
can hold values between 0 and 65,535. Theunsi gned modifier 
can be used with char , i ong, and short (integer) types. 



Each of thedata types (and their modifiers) hasa minimum and maximum value 
(seeT able 2.3). Check your compiler documentation because some compilers extend 
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thesevalues. Becareful nottoassumethatavariablecreated as i nt is either 16 bits or 
32 bits. D ifferent compilers, on different computers, may default the size of an i n t 
variableto either size, depending on theCPU'sdefault integer size. If you must know 
the size of the variable, be sure you specify either i ong or short when you create it. 

When you are entering constants, determining thevalueto use can be difficult. 
For instance, if thefollowing lineisin your program, theresultsprobablyarenot going 
to be what you expected: 

tdefine I NT_ MAX 0 x 80 0 0 /* Really not a good idea! */ 

I n thisexample, you expect i nt max to contain thevalue(- 32768); thecompiler 
promotes the constant to unsi gned, however, and the value of i nt max, 32,768, is 
probably not what you expect. 

A much easier solution exists. A number of useful identifiers aredefined in the 
limits.h header file in ANSI C (see Table 2.3). Use limits.h so that predefined 
identifiers can definethelimitsfor theinteger datatypes. Thevalues shown in Tables 
2.3 through 2.5 represent theAN SI limits, although many compilers exceed thevalues 
shown. 



Table 2.3. C's int limits identifiers, from limits.h. 
Identifier Value Description 

char types 

CHAR_BIT 8 N umber of bits in a c ha r type 

SCH AR_M IN -127 M inimum signed char type 

SCH AR_M AX 127 M aximum signed c har type 

UCHAR_M AX 255 M aximum unsigned char type 

CH AR_M IN SCH AR_M IN M inimum char value, if characters 

are unsigned 

CH AR_M AX SCH AR_M AX M aximum c har value, if characters 

are unsigned 

CHAR_MIN 0 If characters are signed 

continues 
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Table 2.3. continued 



Identifier 



Value 



Description 



CH AR_M AX UCH AR_M AX 
MB LEN MAX 1 



SH RT_M IN 
SH RT_M AX 
USH RT_M AX 
INT M IN 
INT_M AX 
UINT_M AX 

LONG_M IN 
LO N G_M AX 
ULONG MAX 



I f characters are signed 

M aximum number of bytes in 
multibytechar 



short i n t types 

-32767 M inimum (signed) s ho r t type 

32767 M aximum (signed) s ho r t type 

65535 M aximum unsigned s ho r t type 

-32767 M inimum (signed) i nt type 

32767 M aximum (signed) i nt type 

65535 M aximum unsigned i nt type 



I ong 
-2147483647 
2147483647 
4294967295 



nt types 

M inimum (signed) i ong type 
M aximum (signed) long type 
M aximum unsigned long type 



Three different-size variables can be defined for floating-point variables (see 
Table2.4). Theidentifiersfor floating-point numbers are subdivided into three parts. 
Thefirstthreelettersindicatethesizeof thefloating-point object: DBL_ for a d o u b i e, 

FLT for at i oat , and LD BL for aiong double. 



Table 2.4. C's floating-point limits identifiers, from float.h. 



Identifier 



Value 



Description 



D BL DIG 



15 



N umber of 
decimal digits of 
precision 
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Identifier 

DBL EPSILON 



Value 

2.2204460492503131e-016 



D BL_M AN T_D IG 53 

D B L_M AX 1.7976931348623158e+308 
DBL MAX 10 EXP 308 



DBL MAX EXP 



DBL MIN 



FLT EPSILON 



1024 



2.2250738585072014^308 



D BL_M I N_10_EXP (-307) 

D BL_M I N_EXP (-1021) 

D BL_RAD IX 2 

DBL_ROUNDS 1 

FLT DIG 7 



1.192092896e-07F 



Description 

Smallest value 
that, added to 
1.0, makes the 
result no longer 
equal to 1.0 

N umber of bits in 
mantissa 

M aximum value 

M aximum 
decimal exponent 

M aximum binary 
exponent 

M inimum 
positive value 

M inimum 
decimal exponent 

M inimum binary 
exponent 

Exponent radix 

Addition round- 
ing: near 

N umber of 
decimal digits of 
precision 

Smallest value 
that, added to 
1.0, makes the 
result no longer 
equal to 1.0 

continues 
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Table 2.4. continued 



Identifier 



Value 



Description 



FLT_M ANT_DIG 24 

FLT_M AX 3.402823466e+38F 
FLT MAX 10 EXP 38 



FLT MAX EXP 



FLT MIN 



128 



1.175494351e-38F 



FLT MIN 10 EXP (-37) 



FLT MIN EXP 



(-125) 



FLT_RAD IX 2 
FLT ROUNDS 1 



LDBL DIG 



19 



LDBL EPSILON 5.4210108624275221706^020 



LDBL MANT DIG 64 



N umber of bits in 
mantissa 

M aximum value 

M aximum 
decimal exponent 

M aximum binary 
exponent 

M inimum 
positive value 

M inimum 
decimal exponent 

M inimum binary 
exponent 

Exponent radix 

Addition round- 
ing: near 

N umber of 
decimal digits of 
precision 

Smallest value 
that, added to 
1.0, makes the 
result no longer 
equal to 1.0 

N umber of bits in 
mantissa 



LDBL MAX 



1.189731495357231765e+4932L M aximum value 
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Identifier Value Description 

LDBL_MAX_10_EXP 4932 Maximum 

decimal exponent 

LD BL_M AX_EXP 16384 M aximum binary 

exponent 

LDBL_M IN 3.3621031431120935063e-4932L Minimum 

positive value 

LDBL_M IN_10_EXP (-4931) Minimum 

decimal exponent 

LDBL_M IN_EXP (-16381) M inimum binary 

exponent 

LD BL_RAD IX 2 Exponent radix 

LDBL_ROUN DS 1 Addition 

rounding: near 

Other identifiers generally are defined in float, h; however, they usually areeither 
CPU -or compiler-dependent. Refer to your compiler manual foradescription of these 
other identifiers, or print float.h to see whether comments in the file help you 
understand the purpose of the identifiers. 

Rather than code constants for these values into your program, you should use 
oneof thepredefined identifiers shown in Tables2.3 and 2.4. Theseidentifiers allow 
for better portability and make the meaning of your program clear. 



Constants 



All homes arebuildings, but not all buildingsarehomes. All I i teral s are con stan ts, but 
not all constants are literals. M aybethis example is not clear, but with the const 
modifier applied to a variable, it becomes nonmodifiable— a constant. Let's look at a 
few constants. Constants can comein any data type that the C compiler supports. A 
special constant, the string, can be used to either initialize a character array or be 
substituted for one. Table 2.5 shows a number of constants. 
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Table 2.5. Constants in C. 



Constant Description 



Comments 



123 



123U 



123L 



i nt , in the smallest 
size and type that 
will hold thevalue 
specified 



unsigned i nt , in the 
smallest size and 
type that will hold 
the value specified 



ong i nt , signed 



123U L i ong i nt , unsigned 



Character constant 



"ABCDE" Character string 
constant 



N ever a decimal point; a unary is 
allowed if thevalue is negative. 
Be careful not to specify a value 
too large for the data type for which it 
is being used. The C compiler may 
changethesize(or to an unsigned 
integer) if necessary to fit the value into 
the specified datatype. 

N ever a decimal point; a unary is 
not allowed because the value 
must be positive. Becareful not 
to specify a value too large for 
thedata type for which it is being used. 
TheC compiler may change the size if 
necessary to fit the value into the 
specified data type. 

N ever a decimal point; a unary is 
allowed if thevalue is negative. 

N ever a decimal point; a unary is not 
allowed because the value must be 
positive. 

A single character, enclosed within 
single quotes. For nonprintable 
characters, you can use\xNN, where nn 
are valid hex digits. 

0 ne or more characters (to the 
limit of 509) enclosed in double 
quotes. For nonprintable characters, 
you can use \ xnn, where nn are valid 
hex digits. 
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Constant 



Description 



Comments 



1.23 



d o u b i e — floating- 
point constant 



Always a decimal point; both leading 
and trailing zeros are optional, but for 
readability, at least one digit should 
precede and follow the decimal point. 



1.23F 



f i oat — floating- 
point constant 



Always a decimal point; both leading 
and trailing zeros are optional, but for 
readability, at least one digit should 
precede and follow the decimal point. 



1.23L 



floating-point 
constant 



long double — 



Always a decimal point; both leading 
and trailing zeros are optional, but for 
readability, at least one digit should 
precede and follow the decimal point. 



The suffixes shown in Table 2.5 can bein either upper- or lowercase. I prefer 
uppercase because a lowercase I is difficult to distinguish from the number 1. If a 
number that does not fit in the default size is presented to the compiler, it either is 
changed to an unsigned type or its size is increased. As an example, when the value 
45000 is en countered, thecompiler assumes that isan unsigned value; 500000, which 
is too large for either a signed or unsigned 16-bit value, ispromoted to a 32-bit i ong 
value. 

String constants present several unique situations. First, unlike numeric con- 
stants, it'spossibleto obtain theaddressof astringconstant.T hiscapability isnecessary 
because string functions use addresses (see Listing 2.1). 

Listing 2.1. BADSTR.C. 

/* BADSTR, written 12 May 1 9 92 by Peter D. Hipson */ 
/* An example of changing a string constant. */ 

tinclude <stdio.h> / / Make includes first part of file 
#i nc I u d e <s t r i n g . h > 

int main(void); // Declare ma i n ( ) and the fact that this program doesn't 

/ / use any passed pa r a met er s . 



continues 
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Listing 2.1. continued 



i n t ma i n ( ) 

{ 

char s z My N a me [ ] = "John Q . Public"; 
char s z Your Name[ 5 0] ; 

szYour Name[ 0] = ' \ 0' ; 

strcpy( szYour Name, sz My Name); // szYour Name is now the same as 

/ / s z My Na me . 

p r i n t f ( " My Na me ' %s ' Your Name ' %s ' \n", 
s z My Na me , 
szYour Name) ; 

s t r c py ( s z My Na me , "My New Name"); // strcpyl) actually receives the 

// address of the constant 
/ / "My New Name" 

p r i n t f ( " My Na me ' %s ' Your Name ' %s ' \n", 
s z My Na me , 
s z Yo u r Na me ) ; 

p r i n t f ( " B e f o r e : My N a me ' %s ' Constant ' %s ' \ n " , 
s z My Na me , 
"My New Na me " ) ; 

strcpyl "My New Name", // strcpyl) actually receives the address 
s z Y o u r N a me ) ; / / of t h e c o n s t a n t "My N e w N a me " 

// This will fail and destroy the constant! 

p r i n t f ( " Af t e r : My N a me ' %s ' Constant ' %s ' \ n " , 
s z My Na me , 

"My New Name"); // The result can be seen because QuickC 
// for Windows keeps identical strings 
// constants with only a single copy in 
// memory, and they are not read-only. 
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return ( 0) ; 

} 



In Listing 2.1, st rcpyi ) receives two addresses— adestination stringandasource 
string. When theprototypeforst rcpyi ) is examined bythecompiler, it sees that the 
second parameter is a constant and that it will not be modified. T he first parameter, 
however— the destination— is not a constant and can be modified. Compiling the 
examplein thelisting enables you to determinewhether your compiler keeps separate 
copies of strings that are identical or keeps only one copy (in an attempt to conserve 
memory). You cannot depend on thecompiler to storeidentical strings either oncein 
memory or separately for each occurrence. N or can you depend on thecompiler (or 
theC PU ) to makea string constant read-only. 0 n some systems, thisattempt causes 
an error (at execution time); on others, the program generally fails. 

E xcept for string con stants, obtai n i n g th e add ress of a con stan t or m od i fyi n g th e 
constant is not possible. U sing theaddressof operator (&) on a constant isn't allowed. 

Because a string literal can be more than 500 characters long, and because it is 
difficult (or even impossible) to edit sou rce I i n es th at areth at long, you can concatenate 
string literals. The process is easy becauseno operator isused— you simply follow one 
string literal with a second (or third): 

char s z My Ad d r ess[ ] = 
"John Q. Pub I i c\ n" 
"123 Mai n St r eet \ n" 
"Our Town, NH 0 3 4 5 8 \ n"; 

In this code fragment, thevariables z My Ad d r ess pr i nts as th ree I i n es ( because of 
theembedded\ n newlinecharacter). T heinitialization is easier to read becauseit'snot 
spread out on a single line; rather, it is formatted the way it should look. 

Definitions versus Declarations 

There is a difference between defining an object and declaring it. This section looks 
at the differences and the information that should be provided to the compiler in 
defining and declaring objects. 
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B oth data obj ects (variables) an d f u n cti on s are def i n ed or decl ared .This ch apter 
discusses only variables; however, the concepts are the same for a function also. 

The difference between defining and declaring a data object isthat, when a data 
object isdeclared, only its attributes aremadeknown tothecompiler. W hen an object 
is defined, not only are its attributes made known, but also the object is created. For 
avariable, memory is allocated to hold it; for a function, its code iscompiled into an 
object module. 

Because this chapter deals with data objects, this section looks at both declara- 
tions and definitions. 



Declarations 

The simplest declaration of a variable is shown in the following code fragment: 

void Our Funct i on( 
i nt nType) 

{ 

i nt n T e s t ; 

nTest = nType; 

} 

In the fragment, an integer variable is defined. That is, both its attributes (the 
variableisan integer) were made known to thecompiler, and storage was allocated. 
Because thevariable is located in afunction, its scope is limited and itslifeisauto (by 
default, you can change it). This means that each time our Funct i on( ) is called, the 
storageforthevariablenTest isreallocated automatically (usingC'sstack). N oticethat 
nTest wasn't initialized when it wasdeclared. This isn't good programming style. To 
prevent your using an uninitialized variable, I recommend that you initialize all auto 
variables. 

T hefol lowing fragment shows a declaration for a static variable. T he difference 
isthat th e stati c var i abl e's storage space i s al I ocated by thecompiler when theprogram 
is compiled; and because the storage space is never reallocated, it remembers its 
previous value. 
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void Our Funct i on( 
i nt nType) 

{ 

static int nTest; 
nTest += nType; 

} 

You do not initialize this declaration either. Fortunately, however, because the 
compiler initializes static variables (to zero), the preceding function works and adds 
nType to nTest every time the function is called. If the function were called enough 
times, it is likely that nTest would not becapableof holding theconstantly increasing 
sum, and that an integer overflow would occur. 

A fatal error? Perhaps, but on most implementations, integer overflow isn't 
caught as an error, and on these systems (and compilers), this error doesn't cause any 
warning messages to bedisplayed to the user. The only solution isto makesurethat 
nType, when added to nTest , doesn't overflow. 

Whenever a variable is defined within a function, it has local scope. Whenever a 
variable is defined outside any functions, it is said to have global scope 

In each of the preceding examples, you have created a variable that is known 
within the function and that cannot be referenced by any other function. M any 
programmers (almost all of whom are very good programmers) will argue that a 
variable should be known within asinglefunction, and for any external data objects 
to be known, the objects should be passed as parameters. 

Experience has shown, however, that this viewpoint can be idealistic. You often 
will want to share variables between a number of functions, and these variables may 
beunknown to thecaller. Common usesincludecommon buffers, storageareas, flags, 
indexes, tables, and so on. 

To enable a variable to beused by more than onefunction, it must be declared 
outsideanyfunction— usuallyverynearthetop of thesourcefile(seeC hapter 1, "The 
C Philosophy"). An example is shown in Listing 2.2. 
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Listing 2.2. An example of a global variable, in a single source file. 

long int I S u m; // Using ' i nt ' is optional, 
long int I Count ; 

void S u ml n t ( 

int n I t em) 

{ 

I S u m += ( I o n g ) n I t e m; 
+ +1 Count ; 

} 

void Subl nt ( 

int n I t em) 

{ 

ISum - = (long)nltem; 
- I Count ; 

} 

int Aver age( ) 

{ 

int n Re t u r n = 0 ; 

n Return = ( i n t ) ( I S u m / ICount); 
return ( n Ret u r n ) ; 

} 



T he preceding code fragment has a set of two functions that add to a sum and 
count (used to create an average), and return an average. 

If you look at the Aver a ge ( i function, you may wonder why I thought that I 
could divide two i ong (32-bit) integers and be sure that I would get a returned value 
that fit in ashor t (16-bit) integer. The answer is easy because I know that I've never 
added to the sum a value that was larger than would fit into ashor t integer, and that 
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when thesum wasdivided by thecount, the result had to be smaller than (or equal to) 
thelargestvalueadded.Or, will it?No. I madea bad assumption becausesu mi nto can 
add a largenumber, and s u b i nt ( ) then could remove a smaller number. 

Again, in thepreceding example, all three of thefunctions are located in asingle 
source file. What if each of these functions is large and you need to have three source 
files? For that, you must use both declarations and definitions 

Definitions 

Assume that your three functions are larger than they really are, and that each one 
therefore has its own sourcefile. I nth is case, you must declarethevariables(but in only 
one file) and then define them in the other files. Let's look at what this declaration 
would look like. Listing 2.3 shows each of thefiles. 

Listing 2.3. An exampleof a global variable, in three source files. 

Fl LE- SUMI NT. C 

/* SUMI NT. C routines to sum integers and increment a counter. */ 

/* Declare the variables that will be shared between these functions. */ 

long int ISum; // Using ' i n t ' is optional, 
long int I Co u n t ; 

void S u ml n t ( 

int n I t em) 

{ 

ISum += ( I o n g ) n I t e m; 
+ + I Co u nt ; 

} 

Fl LE- SUBI NT. C 

/* Declare the variables that will be shared between these functions. */ 

continues 
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Listing 2.3. continued 

extern long int I S u m; // Using ' i n t ' is optional, 
extern long int I Count; 

/* SUBINT.C routines to de-sum integers and decrement a counter. */ 

void Subl nt ( 

int n I t em) 

{ 

ISum - = (long)nltem; 
■ ■ I Count ; 

} 

Fl LE- AVERAGE. C 

/* AVERAGE. C routines to return the average. */ 

/* Declare the variables that will be shared between these functions. */ 

extern long int ISum; // Using 'int' is optional, 
extern long int I Count; 

int Average! ) 

{ 

int n Re t u r n = 0 ; 

n Re t ur n = ( i nt ) ( I Sum / I Count ) ; 
return ( n Ret u r n ) ; 

} 



Noticethatthetwo variables! sumandi count intheSU BINT.C andAVERAGE.C 
files are defined— using the e x t e r n attribute. This definition tells the compiler what 
the variables' attributes are (long int), and tells the compiler not to allocate any 
memory for these variables. Instead, the compiler writes special information into the 
object moduleto tell thelinker that these variables are declared in a different module. 



34 



Data Types, Constants, Variables, and Arrays 



c cc 



In both files, this information constitutes a definition of the variable, but not a 
declaration (which would haveallocated thestorageforthevariablethreetimes— once 
for each file). 

You might ask what would happen if the variables never were declared in any 
module. The linker (not thecompiler) usually istheoneto complain, by displaying 
an error message. The typical error message is that an object was undefined (the 
message provides the name of the object). Don't confuse the linker's use of the word 
defined with theC compiler's use of it: The linker doesn't use the word defined in 
exactly the same way as the compiler uses it. 

WhenANSI C usesthemodifier s t at i citsmeaningchangesdependingonthe 
context of how it isused. T o help you understand thedifferences, thefol I owing section 
describes variables and their scope and lifespan. 

Variables 

Variablesmakeit all happen. U nlikeconstants, avariabledata object can bemodified. 
C'suseof variables can be rather complex when you consider its capability to modify 
any variableeither directly or by using its address. Any data object that can bedefined 
asa singular variablecan bedefined also as an array. Thedefinition (and use) of arrays 
is discussed later in this chapter. 



Variable Typesand Initializing Variables 

A variablecan be of any type that C supports: an integer or character, or composed of 
compound data objects— structures or unions. Thissection discusses someexamples. 

In thefollowing declaration, ncount isan integer: 

i nt nCount; /* An integer of default size, uninitialized */ 

0 n most PC s, it is a s h o r t i n t ; when it is compiled with one of the 32-bit 
compilers (or under a different operating system), however, it can be a 32-bit long 
integer. 

long ICount = 0; /* An integer of long size, initialized */ 

Thisdeclaration leaves no doubt about the size of the object. First, becausei ong 
andshor t aredefaultedtointegertypes(tocreateai ong doubi e,you mustspecifyi ong 
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d o u b i e in your declaration), the keyword i nt is optional. It might be better styleto 
includeit (I usually try to). T hevariablei count isinitialized explicitly; if it were a static 
variable, this initialization would beoptional, but by including it, you can besureof 
its value. 

char c KeyPr essed = ' \ 0' ; 

This declaration is interesting: Because the data type is character, it must be 
initialized with the correct type. Because character constants are enclosed in single 
quotes, this initialization works well. I don't recommend it, but you can use 

char c KeyPr essed = ( c h a r ) NULL; 

BecausetheNULL identifier is intended for use asa pointer value, thecast to type 
char isn't a smart idea. This hasn't prevented much C code from being written in 
exactly this way. 

Look at thefollowing floating-point number: 

f I oat f Ti meUsed = 0. OF; 

If this code had been written before the AN SI C standard was written, the 
initialization probably would look like this: 

f I oat f T i meUsed = ( f I o a t ) 0 . 0 ; 

Itwasnecessarytocastthedoubi e to at i oat becausetherewasno other way to 
specify at i oat value. 

Because the default floating-point constant size is d o u b i e , thefollowing initial- 
ization is fine. 

double d T i meUsed = 0.0; 

ANSI introduced thei ong doubi e,adatatypethatwasnot often found in various 
C implementations: 

long double fTimeUsed = 0.0L; 

Again, becausethedefaultfloating-point constant isad o ub i e , thesizeisspecified 
in the initializer. This specification definitely is much easier than specifying a cast of 
(long double), unlessyou liketo type. 

Thischapter discusses character string declaration later, in the"Arrays" section. 
In all cases, C creates strings using arrays of typecnar becausethereisno distinct data 
type for strings. 
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Scope (Or I Can See You) 



Thescopeofavariableisoften oneofthethingsprogrammersdon't understand atfirst. 
D epending on where they are declared, variables can be either visible or not visible. 

Let's look at an exampleof scope that showssomepoor programming practices. 
SCOPE.C iscreated in Listing 2.4. Because the program has two variables with the 
same name, it can be difficult to know which variable is being referred to. 

L isting 2.4. SCOPE.C. 

/* SCOPE, written 15 May 1 9 9 2 by Peter D. Hipson */ 
/* An example of variable scope. */ 

#i nc I u d e < s t d i o . h > / * Make includes first part of file */ 
#i nc I u d e <s t r i n g . h > 

int main(void); /* Declare ma i n ( ) and the fact that this program doesn't 



i nt nCounter =0; 

do 

{ 

int nCounter = 0; /* This nCounter is unique to the loop. */ 

nCounter += 3; /* Increments (and prints) the loop's nCounter */ 
p r i n t f ( " Wh i c h nCounter is = %d ? \ n " , nCounter); 

} 

while (+ + nCounter < 10); /* Increments the function's nCounter */ 
pri ntf( "Ended, which nCounter is = %d ? \ n " , nCounter); 
return ( 0) ; 



use any passed p a r a me t e r s . * / 



i nt 



ma i n ( ) 
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This is the result of running SCOPE.C: 
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Ended, which nCount er is = 10? 

N oti ce th at n c o u n t e r was n ever greater than threeinadetheloop. The reason i s 
that the variable is being reallocated from within the do { } block, and, because it is 
initialized, it is set to zero when it is reallocated. To create a variable that can be used 
in theloop and still not havescopeoutsidetheloop, you haveto createadummy block: 

{ 

i nt nCounter = 0; /* This nCounter is unique to the loop */ 

do 

{ 

nCounter + = 3; /* Increments (and prints) the loop's nCounter */ 
p r i n t f ( " Wh i c h nCounter is = %d ? \ n " , nCounter); 

} 

while (+ + nCounter < 10); /* Increments the function's nCounter */ 

} 

T hisexampledoesn't work, however, becausethewhi i eo 'suseof nCounter then 
uses the wrong nCounter . Only one solution exists: Use unique names for variables 
when you are declaring them from within a block in a function. Resist the urge, if you 
areusingthestyleshown inChapterl,"TheC Philosophy," to redefinethef or ( ) loop 
index variables— i , j , and so on. Listing 2.5 shows the successful implementation of 
SCOPE.C. 

Listing 2.5. SCOPE l.C. 

/* SCOPEl, written 15 May 1 9 9 2 by Peter D. Hipson */ 
/* An example of variable scope that works. */ 
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# i n c I u d e < s t d i o . h > / * Make includes first part of file */ 
# i n c I u d e <s t r i n g . h > 

int main(void); /* Declare ma i n ( ) and the fact that this program doesn't 
use any passed p a r a me t e r s . * / 

int ma i n ( ) 
{ 

int nCounter =0; 

{ 

int nCount Loop = 0; /* This nCounter is unigue to the loop */ 

do 
{ 

nCount Loop += 3; /* Increments (and prints) the loop's 

nCounter * / 

p r i n t f ( " n C o u n t L o o p is = %d ? \ n " , n C o u n t L o o p ) ; 

} 

while (+ + nCounter < 10); /* Increments the function's nCounter */ 

} 

pri ntf( "Ended, nCounter is = %d ? \ n " , nCounter); 
return ( 0) ; 

} 



U sing unique variable names is the only way to guarantee that there will be no 
confusion over which variable is being used. T his is a good case of "the language lets 
you do something, but you really don't want to." 



Lifespan (Or H ow Long I s 1 1 GoingTo Be H ere?) 

Determining how long a variable will be kept is another problem that perplexes 
aspiring programmers. Let's look at the keyword modifiers tat i c . This modifier has 
several purposes that, unfortunately, are related. 
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When stat i c is used on avariablefound within a function or block, ittellsthe 
com pi I er n ever to d i scard or real I ocate th e vari abl e. T h e vari abl e i s created at com pi I e 
time and is initialized to zero. The opposite of stat i c in this situation is auto (the 
def au 1 1) . T h at vari abl e, f ou n d i n si de a f u n cti on or bl ock, i s real I ocated every ti m e th e 
function or block is entered. 

W hen s t a t i c isused on a variablethat isdefined outsideanyfunctionsor blocks, 
its meaning is that the variable is known to only those functions contained in the 
specified source file, and are not known outside the source file. When a variable is 
known outsidethesourcefile, itiscalled an external variable. (Don't confusethiswith 
the keyword ext er n .) Theext e r n keyword tdlsthecompilerthatthevariableisbeing 
defined (and not declared). Becauseexter n and stat i c conflict, they cannot be used 
together. The program LIFETIM E.C, in Listing 2.6, shows a variable's lifetime. 

Listing 2.6. LIFETIME. C. 

/* LIFETIME, written 15 May 1 9 9 2 by Peter D. Hipson */ 
/* An example of variable lifetime. */ 

#i n c I u d e < s t d i o . h > // Make includes first part of file 
#i nc I ude <st r i ng. h> 

i nt nLife = {5}; // Initialize to 5, default is 0. 

int main (void); // Define ma i n ( ) and the fact that this program doesn't 
/ / use any passed pa r a met er s . 

void Di s p I ay L i f e( vo i d ) ; // Define Di s p I a y L i f e( ) 

int ma i n ( ) 



int nCou nt er =0; 

do 
{ 

int nCount Loop = 0; /* This nCounter is unique to the loop */ 

nCount Loop += 3; /* Increments (and prints) the loop's 
nCounter * / 
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n L i f e += nCount er ; 

pri ntf("nCountLoop is = %d \ n " , nCountLoop) ; 

} 

while ( + + nCounter < 10); /* Increments the function's nCounter */ 
Di spl a y L i f e( ) ; 

pri ntf( "Ended, nCounter is = %d \ n " , nCounter); 
return ( 0) ; 

} 

void Di s pi ay L i f e ( ) 

{ 

pri ntf( "Di spl ayLi fe( ) , nLife =%d?\n", nLife); 

} 



InLIFETIM E.Cthevariablemi f e isknowntobothmai no and Di spi ayLi f e( ) . 
T his sharing of the variable is an acceptable programming practice and is commonly 
used as outlined previously. 

In the preceding example, if the declaration of mi f e had been the following: 

static i nt nLife = {5}; // Initialize to 5, default is zero. 

the result would have been the same. The reason is that only one source file is in this 
program; therefore, nLife had to be visible in only one file. Whenever possible, 
rememberto makeyour external variabless t a t i c : I f they are known in only onesource 
file, theyaremuch less likdy to be modified unintentionally by another function in a 
different source file. 



Typecasting 

This chapter has referred to type casting, but what is a cast? A cast is C 's way of 
converting a variable of one type to another type. This topic is very important when 
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errorsand misuseof avariable'stypes occur. N othingismoredisastrousin aC program 
than inadvertently assigning a pointer to an integer using a cast and not catching the 
error. 

Won't the compiler give a message? N o. If you cast one type of variable to a 
different type, the compiler assumes that you know what you are doing, and it says 
nothing. Thereisatimeand a place for a cast. Before using one, however, be sure to 
look carefully at your codeand determinethattheeffect of the cast (or the lack of the 
cast) is what you want and expect. 

Listing 2.7 shows theCASTS.C program. A number of variables, all initialized, 
are in this program. First, the initialized values of each variable are printed, a few 
assignments are made, and then the result of these assignments is printed. 

Listing 2.7. CASTS. C. 

/* CASTS , written 15 May 1 99 2 by Peter D. Hipson */ 
/* Using casts to change a data type. */ 

tinclude < s t d i o . h > // Make includes first part of file 
#i nc I u d e <st r i ng. h> 

int main (void); // Define ma i n ( ) and the fact that this program doesn't 
/ / use any passed pa r a met er s . 

int ma i n ( ) 



{ 

f I oat f Val ue = 123. OF; 

double dVal ue = 9 8 7.0; 

I ong double ddVal ue = 123123123123. OL; 

int nlnteger =12345; 

int nlnteger Again =12345; 

long ILong =987; 

unsigned long ulLong = 987; 

char cChar = ' A' ; 



printf(" fValue %f \n dValue %l f \n ddValue %Lf \n " 

"nlnteger %d \ n ILong %l d \ n u I L o n g %l u \ n c C h a r %c \ n " , 
f Val ue, 
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dVal lie, 
ddVal lie, 
nl nt eger , 
I Long, 
u I Long, 
c Cha r ) ; 

/* These assignment statements generate a warning message 
about type conversion. * / 

nlnteger = d Value; 
I Long = ddVal ue; 
ul Long = ddVal ue; 
cChar = nlnteger Again; 

p r i n t f ( " \ n fValue %f \n dValue %l f \n ddValue %Lf \n " 

"nlnteger %d \ n I L o n g %l d \ n u I L o n g %l u \ n c C h a r %c \ n " , 

f Val ue, 

dVal ue, 

ddVal ue, 

nl nt eger , 

I Long, 

u I Long, 

c Cha r ) ; 

/* With a cast, there is no warning message; 
however, the conversion is the same */ 

nlnteger = ( i nt ) dVal ue; 
ILong = (long)dd Value; 
ulLong = (unsigned I ong) ddVal ue; 
cChar = ( char ) nl nteger Again; 

p r i n t f ( " \ n fValue %f \n dValue %l f \n ddValue %Lf \n " 

"nlnteger %d \ n ILong %l d \ n u I L o n g %l u \ n c C h a r %c \ n " , 

f Val ue, 

dVal ue, 

ddVal ue, 

nl nt eger , 

I Long, 

u I Long, 

continues 
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Listing 2.7. continued 

c Cha r ) ; 

printf("\nNotice that ' I Long' and ' u I Long' " 
"both have the wrong value. \ n " ) ; 

return ( 0) ; 

} 



After compiling and running CASTS.C, you get thefollowing result: 

f Val ue 123. 000000 

dVal ue 987. 000000 

ddVal ue 12 312 312 312 3. 000000 

nlnteger 12345 

I Long 987 

ul Long 987 

cChar A 

f Val ue 123. 000000 

dVal ue 987. 000000 

ddVal ue 12 312 312 312 3. 000000 

nlnteger 987 

I Long - 1 4 3 09 2 8 4 6 1 

ul Long 2864038835 

cChar 9 

f Val ue 123. 000000 

dVal ue 987. 000000 

ddVal ue 12 312 312 312 3. 000000 

nlnteger 987 

I Long - 1 4 3 09 2 8 4 6 1 

ul Long 2864038835 

cChar 9 

Notice that ' I Long' and ' u I Long' both have the wrong value. 

You may want to know how ui Long managed to get such a strange value. Your 
first guess probably is that it should have received the least-significant digits from 
dd va i ue ; thereseemsto be no relationship, however, between thevaluei 2 3123123123 
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and theresult held in ui Long of 2 86 4 0 3 88 3 5 .Thedifferenceiseasyto explain, though, 
when you look at the hex values of theconverted number. T he value 1 2 3 1 2 3 1 2 3 1 2 3 is 
too largetostorein asingle32-bit unsigned (or signed) integer. Thehex representation 
of 123123123123 isic aa bs C3 b 3 , a value that requires five bytes to store. Because 
u i Long hasonlyfour bytes, theleading digits, ic, are truncated, leaving theresult that 
is assigned to u i Long : aa bs C3 b 3 (2 8 6 4 0 3 8 8 3 5 in decimal). 

This same type of truncation happenswhen as nor t int is assigned a valuethat 
wasstoredinai ong i nt that wastoo large. For example, if thevaluei 2 3 1 23123 isstored 
in ui Long, when itisassignedtoan unsigned integer theresultis 46 5 1 5 (seeTable2.6). 



Table 2.6. Examples of conversions of C data types. 



Original 
data type 


Original 
in decimal 


Original 
in hex 


C onversion 


Result 
in hex 


Result 
in decimal 


1 ong i nt 


123123123 


0X756B5B3 


To short 

in t , by 
truncating 
(theleading 
0x756 is 
dropped). 


0xB5B3 


46515 


short 
i nt 


12345 


0x3039 


T O c h a r by 
truncating 
and type 
change (the 
leading 0x30 
is dropped). 


0x39 


'9' 


long 
doubl e 


123123123123 


0xlCAAB5C3B3 


C onvert to 
integer, 


0xAAB5C3B3 


2864038835 



and truncate 
(theleading 
OxlC is 
dropped). 



Asshown in Table2.6, it's important to remember that truncation occursusing 
the internal format of the number, not the number you see and use. It is easy to lose 
thenumberyou had, and if you arechanging types (such as from integer to c ha r ), the 
result can be difficult to predict. 
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Casts have their place in C programming. Because your goal should be to have 
your program compile with no warning messages, a cast can sometimes be the only 
way to suppress a warning. 

Whenacastisusedonaparameterusedinafunction call, theeffectispredictable: 
First, the variable is converted to the correct type, and then it is passed. If you have 
prototyped thefunction correctly, thecompiler knowsthedatatypesof theparameters 
and ensures that the conversions are completed, giving whatever warnings are 
appropriate. If no parameter types are provided with the prototype or the prototype 
ismissing, thecompiler doesn't know thecorrect types, makesnoconversionsforyou, 
and issues only a missing prototype message. 

Arrays 

Arrays are collections of identical data objects, known by a common name and 
addressable either asa group or asa singleobject. Any data object that can bedefined 
can bedefined as an array. 

Declaration of Arrays 

Likeasingledata object, arrays have to be declared. Theprocess of declaring an array 
isnotdifficult. You must, however, providethecompiler with somemoreinformation. 
You must tell how many of the desired data objects will be found in the array. For 
example, an array of i nt may bedefined as 

i nt n Ar r a y [ 1 5 ] ; 

In this declaration, an array of integers has been created (remember that a 
declaration allocatesmemory). T hefirst member in thearray isaddressed asn Ar r a y [ o ] , 
and thefinal member isaddressed asn Ar r a y 1 1 4 1 . H ere'san exampleof oneof themost 
common coding errors: 

#d e f i n e MAX SI ZE 20 

int nAr ray[ MAXSI ZE] ; 
i nt i ; 

/ * Ot her lines of code */ 
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for ( i =1; i <= MAX_SI ZE; i + + ) 

{ 

n A r r a y [ i ] = i ; 

} 

In the preceding fragment, the array element n Ar rayi 15] is initialized. Your 
program crashes because there is no dement 15. The probable result isthat some part 
of th e program ( often m u ch I ater past theloop) thatprobably isnot rel ated to th ef ai I ed 
part either producesincorrectresultsor simply crash esand dies. Also, thearray element 
n Ar r a y [ 0 ] is never initialized because the loop starts with thesecond element in the 
array. 

When a foro loop is used to initialize an array, always make sure that the 
following two statements are true: 

1. The initial index value is zero (unless there is a valid reason for some other 
starting value). 

2. When thearray is being tested to the end, the test does not exceed the number 
of elements defined. 

An example of the preceding loop being written correctly shows that the first 
element isinitializedcorrectlyandthattheloopendswiththelast element, nAr rayi 14] : 

for ( i =0; i < MAX_SI ZE; i + + ) 

{ 

n A r r a y [ i ] = i ; 

} 

W orking with arrays can bedifficult, especially when their boundsareexceeded. 
M any C implementations have little or no array bound checking. Generally, you 
should be sure that you have not exceeded the bounds of any arrays in your program. 

Definition of an Array 

An array can be declared with thefollowing line: 

i n t nAr r a y [ 1 5 ] ; 

When an array is external (defined in a different source file), itmustbedefined 
inanyothersourcefilesthatmayneedtoaccessit. Becauseyou don't want thecompiler 
to reallocate the storage for an array, you must tell the compiler that the array is 
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allocated externally and that you want only to access the array. To do this, you use an 
array definition, which might look like this: 

extern int n A r r a y [ ] ; 

This stat em en t tel I s th e com p i I er t wo i m portan t th i n gs: 

1. The array has been declared (and storage allocated) in a different source file. 

2. The size of the array is unknown. 

Because the compiler knows only what you tell it (the compiler doesn't search 
yoursourcefilestofind wherenAr r ay [ ] wasdeclared), it needsat least thenameof the 
array and its type (so that the array can be indexed properly). Although it's not 
necessary, especially in dealing with single-dimensional arrays, to tdl thecompilerthe 
number of dements in an array, the compiler has no way of knowing where the end 
of thearrayis.You must make sure the array is used properly and you don't exceed the 
bounds of the array. 

If you choose to use the following definition: 

extern int n A r r a y [ MAX_ S I Z E ] ; 

you will tdl the compiler at least the number of dements in the array. This is a good 
start in bdngabletoensurethatyou havenot exceeded theboundsofthearray. Again, 
note that the majority of C compilers (whether AN SI or not) do not check array (or 
string) bounds. 



Array Indexing 

When C stores an array in memory, it usesa rather complex set of pointers. Generally, 
you haveto consider only that a block of memory hasbeen allocated for thearray. T hen 
you can work with this memory and let C do the address computations for you. 

At times, however, it's necessary to work with thearray as a single object. The 
most common timeis when thearray must bepassed to afunction. T hemost common 
occurrence of arrays passing to functions is when you pass a string to a character 
function, such asC'sst r i en( ) function. 

Let's look at a simple program that creates one-, two-, and three-dimensional 
strings. ARRAY1, in Listing 2.8, creates three arrays, initializes them using the 
standard C array-subscripting techniques, and then accesses the members in thestring 
using an alternative array indexing method. (I'm not saying that you should use this 
method.) 
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L isting 2.8. ARRAY1.C. 

/* A R RAY 1 , written 18 May 1 9 92 by Peter D. Hipson */ 

/* A program that demonstrates multidimensional arrays. */ 

# i n c I u d e <stdio.h> / / Make includes first part of file 

#def i ne MAX_ COMP ANI ES 3 
#def i ne MAX_ CARS 5 
#def i ne MAX_ MODE L S 10 

// This is a 10- el e me n t array, 
int n A r r a y 1 [ MA X _ C A R S ] ; 

/ / This is a 10- by- 5 array. 

int n Ar r a y 2 [ MA X _ C A R S ] [ MAX_ MODELS] ; 

// This is a 10- by - 5 - by - 3 array. 

int n Ar r a y 3 [ MA X _ C A R S ] [ MAX_ MODELS] [ MAX_ COMP ANI ES] ; 

int main(void); // Define ma i n ( ) and the fact that this program doesn't 
/ / use any passed pa r a met er s . 

int ma i n ( ) 
{ 

int i ; 

i nt j ; 
int k; 

for ( i =0; i < MAX_ CARS ; i + + ) 

{ 

n A r r a y 1 [ i ] = i ; 

for ( j =0; j < MAX _ MOD E L S ; j + + ) 

{ 

n Ar r a y 2 [ i ] [ j ] = ( j * 10) + i ; 

for ( k = 0 ; k < MAX_COMPANI ES; k++) 

{ 

continues 
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Listing 2.8. continued 

n Ar r a y 3 [ i ][j ][k] = (i * 100) + (j * 10) + k ; 

} 

} 

} 

for ( i =0; i < MAX_ CARS ; i + + ) 

{ 

p r i n t f ( " %3 . 3d " , * ( n Ar r a y 1 + i ) ) ; 

} 

p r i n t f ( " \ n " ) ; 

for (i = 0; i < ( MAX_ CARS * MAX_ MODELS) ; i ++) 
{ 

if ( ( i % MAX _ MOD E L S ) == 0) 

{ 

pri ntf( "\n") ; 

} 

pri n t f ( " %3 . 3d ", *( *( n A r r a y 2 ) + i ) ) ; 

} 

pri ntf("\n"); 

for (i = 0; i < ( MAX_ COMP AN I ES * MAX_ CARS * MAX_ MODELS) ; i + + ) 

{ 

if ( ( i % MAX_COMPANI ES) ==0) 

{ 

pri ntf( "\n") ; 

} 

pri n t f ( " %3 . 3d ", *(*(*( nArray3) ) + i ) ) ; 

} 

printf("\n"); 

// Notice that string concatenation makes the pri n t f ( ) for ma t 
// string more readable. Also note the blank line between the 
// format string and the other arguments to pri n t f ( ) . 
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p r i nt f ( 

" & n A r ray 3 %4 . 4 X \ n" 

" & n A r r a y 3 [ 0] [ 0] [ 0] %4. 4X \n" 

" n Ar r ay 3 %4. 4X \ n" 

"*( n A r r a y 3 ) %4. 4X \n" 

"*( *( n Ar r a y 3 ) ) %4. 4X \ n" 

"*(*(*( n Ar ray 3) ) ) %d \ n", 

& n A r r ay 3 , 

&n Ar r a y 3 [ 0 ] [ 0] [ 0] , 
n A r r a y 3 , 

* ( n Ar r a y 3 ) , 

* ( * ( n Ar r ay 3) ) , 
*(*(*( n Ar r a y 3 ) ) ) ) ; 

p r i n t f ( " \ n " ) ; 

pr i ntf ( 

" & n A r ray 3 %4 . 4 X \ n" 

" &n A r r ay 3[ 0] [ 0] [ 0] %4 . 4X \ n" 

" n Ar r a y 3 +1 %4. 4X \ n" 

"*( n A r r a y 3 + 1) %4. 4X \ n" 

"*( *( nAr ray3 + 1) + 1) %4 . 4 X \n" 

"*(*(*( n Ar ray 3 + 1) + 1) + 1) %d \ n" 

"*(*(*( nAr ray 3)) + ((1 * (10 * 3)) + (1 * 3) + (1))) %d \n" 
"nAr r a y 3 [ 1] [ 1] [ 1] %d\n", 

& n A r r ay 3 , 

&n Ar r a y 3 [ 0] [ 0] [ 0] , 

nAr r a y 3 + 1, 

*( nAr r a y 3 + 1) , 

*( *( nAr r a y 3 + 1) + 1) , 

*(*(*( nAr r ay 3 + 1) + 1) + 1) , 

*(*(*( nAr r a y 3 ) ) + ( ( 1 * (10 * 3) ) + (1 * 3) + ( 1) ) ) , 
nAr r ay3[ 1] [ 1] [ 1] 
) ; 

p r i n t f ( " \ n " ) ; 
return ( 0) ; 
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In ARRAY1, notice the three pr i ntto statements. Each of the three arrays is 
accessed in a slightly different manner. This difference, dueto the different number 
of dimensions in each array, dictates how you access them. 

Thesingle-dimensional array is thesimplest type of array in C. To initialize the 
single-dimensional array, n Ar r ay i[ ] , you use a simple loop, which sets each element 
equal to its index: 

for ( i =0; i < MAX_ CARS ; i + + ) 

{ 

n A r r a y 1 [ i ] = i ; 

} 

Next, to initialize thetwo-dimensional array, n Ar r a y 2 [ ] ,you usea pair of loops, 
onefor each index. To initialize thedements, you add asimplemath statement that 
computes the initializer value based on the indexes: 

for ( i =0; i < MAX_ CARS ; i + + ) 

{ 

for ( j =0; j < MAX_ MODELS; j + + ) 

{ 

n Ar r a y 2 [ i ] [j ] = (j * 10) + i ; 

} 

} 

Thisarray, which is more complex than a single-dimensional array, isstill easy 
to use because it has only two indexes. 

Next, to initialize the three-dimensional array, n Ar r ay3[ ] , you use three loops, 
onefor each index. To initialize the elements, you use a simple math statement that 
computes the initializer value based on the indexes: 

for ( i =0; i < MAX_ CARS ; i + + ) 

{ 

for (j =0; j < MAX_ MODE L S ; j + + ) 

{ 

for ( k = 0 ; k < MAX_ COMPANI ES; k++) 

{ 

n Ar r a y 3 [ i ] [j ] [ k] = ( i * 100) + (j * 10) + k; 

} 

} 
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Thisarray, still morecomplexthan either a single- or two-dimensional array, is 
still easy to use, even with its three indexes. When you are using arrays with a large 
number of dimensions, you must make sure that the correct values are being applied 
to each of the indexes. Errors, which usually occur in transposing an array index 
position, can lead to innumerable problems and can be very difficult to find and 
correct. 

This discussion leads to how an array is stored in memory. The methods of 
accessing an array, if you simply useC'sarray indexing, areof no great importance. If 
you arewriting a program, however, that needs to access the array in ways other than 
thesimpleindex method thatC supports, you can benefit from an understanding of 
how C accesses the array. 

First, let's look at a single-dimensional array. In memory, the array's name is a 
pointer to thefirst element in the array. If this pointer is incremented, you can point 
to successive elements in thearray. Figure 2.1 isan exampleof a single-dimensional 
array and how it is accessed. 
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Figure 2.1. A single-dimensional array in memory. 



Figure 2.1 shows that a single-dimensional array is simply a pointer that points 
to the first element in the array. Each successive array element is accessed by 
incrementing the poi nter by the size of the array's elements. 

In Figure 2.2, you can see that a two-dimensional array isaset of pointers that, 
when unmodified by thearray index values, pointto thefirst elementin thearray. Each 
successi ve array elementisaccessed by incrementing thepointersbythesizeof thearray 
and thearray elements. 
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Figure 2.2. A two-dimensional array in memory. 



Figure 2.2 shows that a three-dimensional array is a set of pointers that, when 
unmodified by the array index values, point to the first element in the array. This 
situation is exactly the same as in a two-dimensional array, except that this array has 
an additional addresspointer. Each successivearrayelementisaccessed by incrementing 
the pointers by the size of the array and the array elements 

M ost array accessesareeither for theentirearray (usually to passitasa parameter) 
or for an individual array element. You can treat a multidimensional array as an array 
of arrays. 

Seeing is believing. Compiletheprogram ARRAY1, and run it. Printtheresults 
if you cannot see all oftheprogram'soutputon thescreen at onetime. N oticehowthe 
final two pr i ntf ( i calls reference the array n Ar r ay 3 . This addressing is important to 
understand if you must access an array using indirection. 

Whyuseindirection?l reallycan'tanswerthat.WithAN SI C,l suspect that there 
are few reasonsfor using this technique. Because programming isan art, however, I 
have no doubt that someone will come up with a good reason to use indirection 
addressing for array elements. 
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Using Array Names as Pointers 

In theARRAYl program in Listing 2.8, you used indirection to index an array. This 
indirection tells you that the array name n Ar r a y 1 is in fact a pointer. 0 ne of the nice 
things about AN SI C is it improved theaccessing of arrays. Part of the change is that 
now you can obtain a pointer to an array, and you can specify to C thedimension of 
an array, which enables you to declare a dynamically allocated array and use simple 
array indexing on that array. 

An example of a dynamically allocated multidimensional array is shown in 
Listing 2.9, ARRAY2.C. In this program, an array is created that has more than one 
dimension, using mai i oc( ) . 

L isting 2.9. ARRAY2.C. 

/* A R RAY 2 , written 18 May 1 9 9 2 by Peter D. Hipson */ 

/* A program that demonstrates multidimensional arrays. */ 

# i n c I u d e <stdio.h> // Make includes first part of file 
tinclude < ma I I o c . h > // For memory allocation. 

#def i ne MAX_ COMP ANI ES 3 
#def i ne MAX_ CARS 5 
#def i ne MAX_ MODELS 10 

int main(void); // Define ma i n ( ) and the fact that this program doesn't 
/ / use any passed pa r a met er s . 

int ma i n ( ) 
{ 

int ( *nPoi nt er ) [ MAX_ MODELS] ; 

int i ; 

i nt j ; 
int k; 

nPoi nter = ( i nt ( *) [ MAX_ MODE LS ] ) 

continues 
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Listing 2.9. continued 

ma I I o c ( MAX_ CARS * s i z eof ( * n Po i n t e r ) ) ; 

for ( i =0; i < MAX_ CARS ; i + + ) 

{ 

for (j =0; j < MAX_ MODELS; j + + ) 

{ 

nPoi nter[i ][j ] = ( i * 100) + j ; 

} 

} 

for ( i =0; i < MAX_ CARS ; i + + ) 

{ 

for (j =0; j < MAX_ MODELS; j + + ) 

{ 

pri ntffnPoi nt er [ %d ] [ %d ] = %4d\n", 
i , 
j , 

nPoi nt er [ i ] [ j ] ) ; 

} 

} 

free(nPointer); 
return ( 0) ; 

} 



Thetechniqueshown in ARRAY2 isnot limited to two-dimensional arrays, nor 
do you have to "preallocate" the n p o i nter variable. The variable could have been 
allocated using other techniques also. In ARRAY2, it was allocated using a standard 
declaration statement. 



Strings: Character Arrays 

You shouldbeawarebynowthatC doesn't support strings. M any peopleconsider this 
shortcoming to be serious; because so much of C's power is in the library functions, 
however, the lack of basic string functionality is not a serious shortcoming. 
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The definition of a string is an array of type char . This definition can be mod- 
ified , h owever; becau se th e I i brary string functions assu m e th at stri n gs are arrays of 
type char , it is best to use the default definition. 

A string constant such as -Thi s is a stri ng- can be considered a pointer to a 
character array. 

Because theC compiler cannot generatecodethat knows how long a string is (a 
string's length is never saved), the end of the string must be marked with a special 
character. T hecharacter used to mark theend of a string isN u l l (0x00). D on't confuse 
this use of null with the keyword of the same name. In a character string, the null 
character is the first character of the 256 ASC 1 1 character set. 1 1 has a numeric value 
ofO(thelowercasea hasanumericvalueof98, which meansthatitisthe98th character 
in the ASC 1 1 character set). 

Note that AN SI C doesn't assumeany specific character set. M ostof thetime, 
on the IBM PC family of computers, you use the IBM PC character set, and on most 
other computers you access oneof theANSI character sets. Both thePC character set 
and the AN SI character set are shown in Appendix A, "The ASC 1 1 Character Set." 

I f you look at character string declarations, you can see that they may be sized 
(and initialized) in several different ways. 

Thefollowing declaration creates an uninitialized string with space to hold 19 
characters plus the terminating null. Remember that this string is uninitialized, and 
can contain any characters, many of which might be unprintable. 

char szSt r i ng[ 20] ; 

In thefollowing example, thestring initializeswith the characters!" hi s is the 
t i me. , and theC compiler addstheNun automatically. 

char s z S t r i n g [ 2 0 ] = "This is the t i me . " ; 

Whenever a double quoted string constant is specified, the compiler always 
provides a terminating null . It is unnecessary to provide this null explicitly, as in 

char s z S t r i n g [ 2 0 ] = "This is the t i me . \ 0 " ; 

In this string, thestring is terminated with two nulls. This error is not serious, 
but it isnot necessary, either. Because theinitializing string islessthan 20 characters 
long, the remaining characters in thestring areundefined with most C implementa- 
tions. You should not assume the string will be padded with nulls or any other 
character. 
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In thefollowing example, thelength of thestring is determined bythelength of 
the initializing string. 

char s z S t r i n g [ ] = "This is the t i me . " ; 

This determination can be tricky because, if you change the contents of the 
string, you must be careful not to exceed thelength, which you either must know in 
advance or compute. This type of string declaration generally is used only for string 
constants. Therefore, I recommend that you usetheconst type modifier: 

const char s z S t r i n g [ ] = "This is the t i me . " ; 

U singe ons t helps retain thestring'sintegrity becauseyou can modify it only by 
creating a new pointer to thestring or by passing thestring asa parameter to afunction 
that modifies thestring. U sing c o n s t is helpful in preventing unintended modification 
of a string; it is not absolute insurance, however, that the string's contents will not be 
changed. 

Thefollowing example doesn't work. 

char szStri ng[30] = { ' T ' " h i s is the t i me " ' . ' } ; 

I can think of no reason to try to mixchar and string constants in an initializer, 
becauseyou can simply write the following: 

char s z S t r i n g [ 3 0 ] = { " T " " h i s is the t i me " " . " } ; 

T heexampleis "pushing it" a little, but as shown in Listing 2.9, sometimes you 
can format strings using concatenation to make their final printed format more 
obvious. N oticethat when you are concatenating strings, you don't use commas or 
any other nonwhitespace separator (to the compiler, a comment is a whitespace 
separator). 

Weall knowthatthemostseriousweaknessof stringsunderC isthat they cannot 
bemanipulated directly. You can not assign, test, or comparestrings without using one 
of the library functions, such asstrcpyi ) orstrcmpi ) . 

Using Arrays of Pointers 

Justasyoucan havearraysoftypei m , you can havearraysof pointers. Theuseof arrays 
of pointersisa handy C featureThissectiondoesnotdiscusspointersthemselves, but 
they are described in Chapter 3, "Pointers and Indirection." 
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Let's look at an example of a program called REPEAT. C that readsin strings, 
placesthem in an array, and prints them toaterminal. Thisprogram, shown in Listing 
2.10, forms the basis for the sort program you write in a later chapter. 

L isting 2. 10. REPEAT. C. 

/* REPEAT, written 19 May 1 9 92 by Peter D. Hipson */ 

/* Prints, in the same order, the strings that are entered. */ 

/* On PCs with memory models, you can compile with LARGE model */ 

# i n c I u d e <stdio.h> // Make includes first part of file 
tinclude <string.h> // For string functions 

int main(void); // Define ma i n ( ) and the fact that this program doesn't 
/ / use any passed pa r a met er s . 



#define MAX_ CHARACTE RS 3 2 7 6 7 /* Total max i mu m c h a r a c t e r s */ 

tdefine MAX_ LINES 1 0 0 0 /* Total maximum lines */ 

tdefine Bl GESTLI NE 128 /* The longest line readable from keyboard 

*/ 

/* Although these variables are defined as external, they can 

* be defined inside the function or be allocated dynamically, 

* depending on the program's needs and memory available. 

*/ 



char szl nput[ Bl GEST LI NE] ; 

char szBuffer [ MAX_ CHARACTERS] ; 

char *pBuffer [ MAXLI NES] ; 

int nBufferPointer = {0}; 

int n L i n e = 0 ; 

int ma i n ( ) 

{ 

int i ; 

continues 
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Listing 2.10. continued 

p r i n t f ( 

"Enter lines, when last one is entered\n" 
"provide a End- Of- File (ctrl-Z on most systems)\n" 
"to print the entered t e x t \ n \ n " ) ; 

while ( g et s ( s z I n put ) ) 

{ 

if ( ( nBuffer Poi nter + strlen(szlnput)) > MAXCHARACTERS) 
{ // The line wo n't fit! End input loop, 
break; 

} 

pBuf f er [ n L i ne] = &szBuffer[ nBufferPoi nter] ; 

// The strcpyl) could have been written as: 

// st rcpy( &szBuffer[ nBufferPoi nter ] , szlnput); 

strcpyf pBuffer[ nLi ne] , szlnput); 

// the + 1 skips over the terminating NULL in each string. 

nBufferPoi nter += s t r I e n ( s z I n p u t ) + 1; 

if ( + + n L i ne >= MAX_LI NES) 
{ / / Too ma n y lines! End input loop, 
break; 

} 

} 

// 

// Later, you add a sort to provide sorted output. 

// 

for ( i = 0 ; i < n L i n e ; i + + ) 

{ 

pri ntf( "Stri ng %d ' %s ' \ n " , i , p B u f f e r [ i ] ) ; 

} 

pri ntf("\n"); 
return ( 0) ; 

} 
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This program allocates space for as much as 32,767 bytes of strings, and a 
maximum of 1,000 strings. T heselimitsmay not bereasonablefor a program that will 
beused. Also, when either limit isexceeded, REPEAT. C simply assumes that theend 
of the input file has been reached. In reality, a (meaningful) messageto the user is in 
order. 

Following the #def i ne statements that define your limiting parameters, you 
allocatestorageforthenecessary variables. Asthecommentsin theC program indicate, 
thesevariablescanbedefinedinsidethemai n( ) function; becausean external (or static) 
variable is automatically initialized to zero (or zeroes), however, you don't have to 
initializethevariables. Again, thewayyour program (or function) isused dictateshow 
or where you allocate the storage. 

I n al I ocati n g storage, you createf i rst a character array cal I ed s z b u f f e r that i s u sed 
to hold thestrings asthey areread in. Thenext variable, p b u f f e r , an array of pointers 
to typec h a r , isdeclared. T hefirst member in thisarray points to thefirst string stored 
in szBuf f er , thesecond member in p Buf f er pointstothesecond string stored, and so 
on. 

A count of thenumber of stringsentered bytheuser iskept in mine. T hisvariable 
isinitialized to zero (thefirst string) and is incremented until theuser finishes entering 
strings. It then isused in thef or < ) loop that isused to print the user's strings. 

An index pointing to thecharacter position in s z bu f f er in which thenext string 
will be placed iskept in nBufferPoi nter . This variable is initialized to zero (thefirst 
character position in sz Buff er ) and is incremented by thenumber of characters in each 
of the user's strings until the user finishes entering strings 

The program's input is handled using a whi i e( ) loop, which calls get so , a 
C library function that reads a linefrom stdi n (the keyboard). 

whi I e ( get s ( sz I nput ) ) 
{ 

if ( ( nBuffer Poi nter + strlen(szlnput)) > MA X_ C HA RA CT E R S ) 
{ // The line wo n't fit! End input loop, 
break; 

} 

pBuffer[ nLi ne] = &szBuffer[ nBufferPoi nter]; 

// The strcpyl) could have been written as: 

// strcpy(&szBuffer[ nBufferPoi nter] , szlnput); 
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s t r c py( pBuf f er [ n L i ne] , sz I n put ) ; 

// The + 1 skips over the terminating NULL in each string. 

nBufferPoi nter += strlen(szl nput) + 1; 

if ( + + n L i n e >= MAX_LI NES) 
{ / / Too ma n y lines! End input loop, 
break; 

} 

} 

In theinputwhi i e( ) loop, first you check to seewhether sz But f er hasenough 
room for this line, and then abort the input if there is no more room. Then you add 
thelinetoszBuf f er and updatethepointers. If nomoreinputlinepointersremain in 
pBuf f er , you end the input phase as well. This error checking is not the best, but this 
program is intended to show a usage for an array of pointers— not to show error 
checking. 

When theuser signalstheend of input, theprogram then can process the lines. 
This program alludes only to the fact that perhaps you sort the lines, or count 
characters, lines, and words, or justify thetext or change its case. Who knows, and for 
now, whocares?You havea program that reads lines in and writes them out. 

To writethelinesout, a simpler or( ) loop has been used. This loop simply uses 
printto to print the user's inputted lines: 

for ( i = 0 ; i < n L i n e; i + + ) 

{ 

pr i ntf ( " St r i ng %d ' %s' \ n", i , pBuf f er [ i ] ) ; 

} 

Inthecalltopri ntto ,you usethepointer to thestring in thebuffer rather than 
try to use an array index— again, to show the use of an array of pointers. 



Summary 

C providesthebasic data types necessary to createmost programs. C'sflexibilityisdue 
i n part to i ts capabi I i ty to create n ew d ata types as th ey are n eed ed . T h e I i m i ts of each 
type of variable were described in this chapter. 
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• U sing constants in C is much like using a constant in any other computer 
language. The only different situation is that in C you can modify a character 
constant (even though it's an error). 

• There is a difference between a variable's declaration (which allocates storage 
and defines the variable's attributes) and a variable's definition (which only 
defines the variable's attributes and does not allocate storage). 

• The use and initialization of variables were discussed, along with arrays, 
including using indirection as a method to access an array's members. The 
chapter discussed multidimensional arrays and how they are stored in memory, 
with a demonstration of one-, two-, and three-dimensional arrays provided by 
an example program. 

• The last part of the chapter described arrays of pointers and a simple program 
demonstrated their use. 
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Table 1. 1. ANSI compiler minimums. 



M inimiim 

1*1 lllllllillll 


Item 

1 LCI II 


c 
0 


bigmricant cnaracters in an external name 


8 


#i nc i ude nesting 


o 
0 


#i f , #i f ndef , #i f def and #el i f 


12 


o,[], or * in a declaration 


15 


N ested compound statements 


15 


Levels of st r uct or union nesting 


31 


( i declarators within a declaration 


31 


Significant characters in a macro or identifier 


31 


Parameters passed to a function or macro (important for 




pr i n t f ( ) , s c a nf ( ) , ana SO On) 




Levels of nested parentheses 


Li 1 


Local luentiriers in aoiocK 


127 


M embers in a singles t r u c t , u n i o n or enu m 


257 


case statements in a switcho statement 


509 


C haracters in a literal string (after any concatenation) 


511 


External identifiers in a single source file 


1024 


Simultaneously defined macros 


32767 


Bytes in a single data object 



Of course, nothing prevents a compiler producer from extending these limits; 
however, you should review the documentation supplied with your compiler to see 
whether any(or all) limitsaredifferentfrom theAN SI standard. If your compiler does 
extend these limits and you use the extensions, you can be sure that when your 
program iscompiled with another compiler, it will either not compilecorrectly or not 
execute correctly. 
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Someof theselimitswill change(soon, I hope) with futurerevisionsof theAN SI 
specification. One of the most bothersome limits, six significant characters in an 
external name, was issued because some linkers cannot use more than the first six 
charactersin an external name. Asnoted by theAN SI standards committee, thislimit 
is a rather poor one and probably will change soon. If your compiler doesn't have a 
published limit on the number of significant characters in an external name, you can 
test it. Compileand link the programs shown in Listing 1.1 (it has two source files). 
Asnoted in the listing, changing the names of thefunctions called (and the missing 
one) can be used to indicate the number of characters that are significant (13 in this 
example) in an external name. 

Listing 1.1. External name lengths for FILEONE.C and FILETWO.C. 

Fl LEONE. C 

void si xchrl234567( voi d) ; 
void si xchrl234567( voi d) ; 

i n t ma i n ( ) 

{ 

si xchrl 2 3 4 5 6 7( ) ; 

sixchrl2345678(); /* Will be unresolved external if mo re than */ 
/* 13 characters are significant. */ 

} 

Fl LETWO. C 

void si xchrl 2 3 4 5 6 7( ) 

{ 

return; 

} 



Another significant factor in external namesisthat most linkers ignorecase. You 
should be very caref u I , th eref ore, not to havetwo functionsthat differ only in the case 
of their names, such asin thefollowingexample(in which both functionsareexternal): 

Ou r P r i n t e r ( ) ; /* Print, using initial caps. */ 

OURPRI NT E R ( ) ; / * P r i n t , u s i n g a I I c a p s . * / 

o u r p r i n t e r ( ) ; /* Print, using only lowercase. */ 
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In this fragment, the three different names will be linked to the same function 
by the linker. Some linkers have the option to retain case, which solves this problem, 
but many don't. Be careful: I got burned by this one once, and ittookalongtimeto 
determine why the wrong function was being called. (I didn't know about the other, 
different-case function). 

A number of keywords are reserved in ANSI C (seeTable 1.2). You must be 
careful nottousethesenames(all of theAN SI keywordsarein lowercase) asidentifiers 
in your program. Generally, the compiler "complains" when you incorrectly use any 
reserved keyword. 



Table 1.2. ANSI C reserved identifiers. 



Keyword Usage 



asm Begins assembly code and is not part of theAN SI standard. 

Fortran The entry follows FORT RAN calling conventions; FO R- 

TRAN maybein lowercase for some implementations and 
is not part of theAN SI standard. 

pascal The entry follows PASCAL calling conventions; PASCAL 

maybein lowercase for some implementations and is not 
part of theAN SI standard. G enerally, the PASCAL conven- 
tions are identical to FO RT RAN 's. 

const T he variable will be used as a constant and will not be 

modified. 

volatile The compiler may make no assumptions about whether the 
variable's value is current. This keyword limits optimization, 
and possibly slows program execution. 

signed T he variable is a s i g n ed integer (with the actual size 

unspecified). 

auto The variable is created when thefunction is called, and is 

discarded when thefunction exits. An auto variable is not 
initialized by thecompiler. 



continues 
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Table 1.2. continued 



Keyword Usage 



break E nds the enclosing do ( ) , f or ( ) , swi t ch( ) /case Or whi I e( ) 

statement and is used most often to end a c a s e statement. 
Using break outsideof aswi t cm i /case block may be 
considered to be unstructured programming, in the same 
way that embedded return statements are considered by 
some programmers. 

case Used with theswi t ch( ) statement to mark the beginning of 

a group of statements that are executed when the c a s e 's 
value matches the swi tend statement's value. Execution 
continues until abreak statement isencountered or no more 
statements are in theswi t ch( i statements. 

char A character variable that may be either signed or unsigned. 

continue Passes control to the next iteration of a d o ( ) , f o r ( ) , or 
whi i e( i statement. 

default Used with aswi t ch( i statement, the statements following 

the d ef a u 1 1 statement are executed until the first break 
statement if no case statement value matches the swi t cm i 
statement's expression. 

do Used with thewhi i e( i statement, the statement or state- 

ments between the do and the closing whi i e( ) are executed 
until thewhi i e( i condition evaluates to false. The state 
ments between are executed at least onetime. 

doubi e An eight-byte floating point variable. 

else Used with the i f ( ) statement, the statement or statements 

within the else block are executed if the i f ( ) expression 
evaluates to false. 

enum An integer defining a rangeof values. The actual internal 

representation of the value is not significant. 

extern T he object is defined in a different source file. 

float A four- byte floating point variable. 
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Keyword Usage 



for The iterative loop statement for C. Enables one (or more) 

identifiers to be initialized, tested, and modified. 

goto Causesan unconditional branch (change flow of execution). 

(M any programmers consider using goto to be one step 
short of sacrilege). 

i f C auses execution of a block of statements depending on the 

logical evaluation of the i f ( ) statement's expression. 

i nt Theobject is defined as an integer (with a default size 

dependent on the CPU 's default integer size. 

long Theobject is defined asa i ong (four-byte) integer. 

regi ster Theobject (usually an integer) is retained in oneof the 
CPU 's registers whenever possible. The compiler often is 
forced to remove the variable from the register to perform 
various other tasks, however. This keyword can help speed 
program execution when a variable must be accessed 
frequently. 

return C auses a function to return to its caller. M ost programmers 

insist that there beonly one return statement at the end of a 
function. Theret um statement may specify a value to be 
returned to the caller if the called function was defined as 
returning a value. 

short A two- byte integer. 

si zeof Returns the size of a specified data object, which can be a 

simple data type, structure, union, or other complex data 
object. 

static A data object created when the program is linked and 

initialized (to zero), and retains its value throughout the 
program's execution. The opposite of an auto variable. 

struct Used to define or declare a complex data type, which can 

consist of a number of different data types. 

continues 
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Table 1.2. continued 



Keyword Usage 



switch U sed with an expression (that must yield either a long or 

short integer), which used with thecase statement, allows 
for conditional execution of code based on the current value 
of the expression. 

typedet Al I ows creation of a specific data type that is not part of C's 

provided data types. U sually (but not always) used with 
either struct or u n i on to create complex data types. 

union Creates a complex data type in which two or more variables 

occupy the same data memory at thesametime. Often used 
to enable the reading of different types of records into a 
common buffer, which then can be referred to with the 
correct type variables 

unsigned An unsigned integer (either long or short) alwayscan 
contain only positive values. 

void Defines a function that either doesn't return a value or has 

no parameters, or defines a pointer to a variable of an 
unspecified type. An object pointed to by a voi d pointer 
cannot be directly modified. 

while Used either alone or with the do statement to conditionally 

execute statements until the whi i eo 's conditional statement 
evaluates as false. 



Even with the AN SI set of reserved keywords, you can generally expect that a 
specific compiler may reserve, as necessary, other words as well. A number of key- 
words are reserved also for library names, for example. Table 1.3 lists these reserved 
names. 



Table 1.3. ANSI C reserved names. 
N ame U sage 

% Used in a pr i ntt ( i /scant ( i format string; to create a 

literal percent sign, use%% 



10 



T he C Philosophy 



cr. c 
cc c 
ccc 



Name 


Usage 


i s ... orto... 


Lowercase function names beginning with either i s orto, 




wh ere th e n ext ch aracter al so i s a 1 owercase 1 etter 


st r mem..., 


Lowercase function names beginning with either 


or wc s ... 


s t r , me m, or wc s , where the next character also 




is a lowercase letter 


E 


M acrosthat begin with an uppercase e 


si g... orsi G_... 


M acrosthat begin with either an uppercase si g or si g 


...f or ...i 


Existing math library names with a trailing f on 




M acrosthat begin with an uppercase lc 



As you can see from Table 1.3, there are a number of reserved prefixes and 
postfixes; it isn't difficult, however, to find a suitable name, because all these reserved 
names are either all uppercase or all lowercase— just using mixed-case names should 
enableyou to avoid conflictswith thereserved namesin AN SI C (remember that some 
linkers ignore case). 



A Programming Style 

I know that at least half of all C programmers use a formatting style different from the 
onel'm going to propose. I can't resist, however— I've used this style for years (longer 
even than I 'veprogrammed in C ), and I can (and will) justify whyyou should consider 
using it. 

Let'slookatthestylein which all theexamplecodein thisbook ispresented.The 
following list shows a few simple rules. 

1. Each tab stop is indented four characters. 

2. Lines should be a maximum of 80 characters if at all possible. 

3. Comments can use either the AN SI standard/* comment */ or the newer// 
single line comment (supported by many compilers even though it's not part 
of the AN SI standard). 
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4. When variables are defined or declared, only one variable is allowed per 
definition or declaration. 

5. All functions are prototyped, either in the header includefile, or if there is 
none, at the top of the file. 

6. All data objects (variables) useH ungarian notation (see Table 1.4) and are 
mixed case. 

7. All function names are mixed case and should be descriptive of what the 
function does. If the return is not clear, useH ungarian notation for the 
function name. 

8. Opening and closing braces are on their own lines, aligned in the same 
column. In either case, a comment (one or more lines) may be used to 
describe what the particular block of code is doing. 

9. Document why, not what, you are doing. For example, you always can see that 
you are incrementing the variable, but you can't always see why you had to 
increment it. C omments are just notes to yourself (and perhaps others) 
reminding you of what you did. It's almost painful to go back to a complex 
piece of code and find that you no longer understand it. It's easier to rewrite 
poorly documented code than to try to figure it out. 

10. Use blank lines wherever necessary to make the code readable. 

11. Use the variables i , \ , k, i , m, and n ast or { ) loop indexes, and use them in 
order. U sing this rule saves many hours of trying to figure out which index is 
changing faster. Avoid using these variables for scratch variables 

12. Avoid "cute" code. You may think that it makes you look likeyou're the 
world's greatest programmer; however, you will have unreadable source code 
that is difficult to maintain. If you must create a relatively strange piece of 
code, don't forget to document what it's doing and why you needed to create 
it. Don't make yourself have to go back and ask, "Why did I do that?" when 
you might realize that therewas an easier way to get thejob done. 

13. Use parentheses liberally. When in doubt, use them. Then you can besurein 
what order things will be done. 

14. Use the "new"-style function headers. This style, as shown in the code frag- 
ment later in this section, is much easier to read because the variables and their 
types and order are clearly defined. Thefact that you can't assume that the old 
style will remain in future releases of the standard is a good incentive to switch. 
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H ungarian notation prefixes a variable name with a letter or letters to tell the 
programmer what data typethevariablecontains(seeT ablel.4). T histypeof notation 
is very helpful when you must maintain theprogram later. H ungarian notation helps 
to prevent assigning the wrong data typeto a variable, and helps you understand why 
you are using a particular data object. 

Table 1.4. Hungarian notation prefixes. 
Prefix Description 

C char 

by BYT E (unsigned char) 

n short i n t 

x Usually as hor t i nt , used for x coordinate in graphics 

y Usually ashor t i nt , used for y coordinate in graphics 

i i nt 

b BOOL(int) 

W WORD (unsi gned i nt ) 

h HANDLE (WORD) 

dw DWORD (unsi gned long i nt ) 

fn Function, usually used with function pointers 

s Character array (not necessarily null terminated) 

sz Character string (must be null terminated) 



M odifier 


Description 


P 


Pointer 


IP 


i ong (or far) pointer 


np 


shor t (or near ) pointer 



Although itoften isrecommended that programmersusethesesameprefixes for 
functions, I dosoonlyifthefunction'sreturntypeisnotobviousanditdoesnotreturn 
an i n t . 



13 



Parti • HoningYour C Skills 



When you are writing a function, you must have a function declaration. The 
new-style function declaration (the header, as it sometimes is called) looks like the 
following example, when it is formatted as I have suggested: 

i nt My F u n c t i o n ( 

i n t n F i r s t P a r a me t e r , 
char szSt r i ng[ ] , 
char chMode) 

{ // Function's opening brace 

The preceding example is basically the new ANSI C style, with each of the 
function'sparameterscoded on aseparatelinefor readability. Thesameexamplein the 
old style (I do not recommend this method) looks like this: 

i nt My F u n c t i o n ( n F i r s t Pa r a me t e r , szStringM, chMode) 
i n t n F i r s t P a r a me t e r ; 
char szStringM; 
char c hMode; 

{ // Function's opening brace 

I f for no other reason, you should usethenew stylebecauseit requireslesstypi ng. 

L et's I ook at a pi ece of wel I -form atted code. Listing 1.2 isasimpleprogram that 
prints on thescreen a message that isan implementation of the standard H ELLO .C. 
Comments about the formatting are in italic type to highlight them, but these 
comments are not necessary in the program. 

Listing 1.2. HELLO. C. 

/* HELLO, written 12 May 1 99 2 by Peter D. Hipson */ 
/* A source formatting example. */ 

tinclude <stdio.h> // Make includes first part of file 

int main (void); // Declare ma i n ( ) and the fact that this program doesn't 
/ / use any passed p a r a me t e r s 

int ma i n ( ) 

{ // First opening brace for each function is at the left margin 
int i; // Used as a for loop index 
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i nt 
char 



nCount = 0; // Always initialize your auto variables 

szStringll = "We want to impress you %d\n"; 



for (i =0; i < 5; i + + ) // Spaces around operators 
{ / / Br ace on i t s own I i ne 



nCount += printf(szString, i + 1); 
} /* for (i . . . ) */ 



return (nCount); 



// Brackets around all return values 



} // Closing brace for a function is at left margin also. 



N oticein Listing 1.2 that if you draw a vertical linefrom any opening brace, you 
eventually can connect with its closing brace. Therefore, you can easily see the various 
blocks that are part of the code. When you place the opening brace at the end of the 
preceding line(f or ( ) in theexample), it'sdifficulttomoveupfrom aclosingbraceand 
find its opening counterpart. 

All the variables declared in the function, except for the loop counter, are 
initialized. Neglectingtoinitializeavariableisperhapsthemostproblematicerror that 
C programmers make. Itseemsthat, at some point, wemakean assumption that the 
contents of a variable are valid, we use it, and the program crashes. 

I recommend that you order your C source files in this order: 

1. Use a one-line file description with the filename (it can be handy when it is 
printed), the entire project's name, and perhaps the initial date written and the 
programmer's name. 

2. Add #i nci ude statements. Remember to comment i nci ude files that are not 
part of AN SI C and tell what is in the file. It's not unusual for a large project 
to have five or morei nci ude files. I usually have an includefile with typedef s, 
one with prototypes, one (or more) with den nes, and an i nci ude file with 
external definitions. 

3. Following the#i nci ude statements, I recommend a full program header block. 
In the example I use (see Listing 1.2), you can see what information usually is 
included with atypical source file. 

4. After the program header, put the definitions and declarations used in this file 
(and that are not found in the header files). 
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5. List the file's functions. The order of functions in a source file is generally not 
critical. I often reorder the files and place at the top (or end, if I am working 
on two functions at onetime) thefunction on which I am working. This 
ordering makes the function easy to find. I don't recommend that you have 
each 20- or 30-line function in its own source file or that your project consist 
of two or three source files of 10,000 (or more) lines. When a source file is 
more than about 1,000 lines, I break it into two files, if possible. You can load 
the source file into the editor faster, and compile faster most of the time. 

Listing 1.3 sh ows a typi cal h eader bl ock com m en t used i n creati n g a C sou reef i I e. 
Using a header such as this one is helpful when you work on the program again later 
(perhapsyearslater).Themorecommentsyou have, theeasier it isto fixtheprogram. 
Remember that no one will have sympathy for you if you don't understand your own 
programming, even if it's been a while since you worked on it. 

Listing 1.3. A typical source file header block. 



PROJECT: The project's name goes here. 

Tl TLE: The FILE'S title ( not the proj ect title). 

FUNCTION: What the function(s) in this file does. 
Mo re than one line if necessary. 

INPUTS: What generally is passed to the functions. 

OUTPUTS: What the fundi ons return. 

RETURNS: Some functions don't return normally; say so if necessary. 

WRI TTEN: When the file was created. 

CALLS: Significant calls to other parts of program. 

CALLED BY: Who (generally) calls these functions. 



/ 

* * * * 

* * 

* * 

* * 

* * 

* * 

* * 

* * 

* * 

* * 

* * 

* * 

* * 

* * 

* * 

* * 

* * 

* * 

* * 

* * 
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* * 



* * 



AUTHOR: Your name. 



* * 



* * 



NOTES: Modifications, special considerations, and so on. 



* * 



* * 



* * 



COPYRI GHT 1 9 9 2: By whomever . A 
deserved. 



rights reserved. A 



wrongs 



* * 




H ere's a final comment about programming style. Always correct all the 
problems that create compiler warning messages. D oing so may seem to be a bother; 
the messages wouldn't be there, however, if they were not important. M akeitagoal 
to h aveyou r program ( n o matter h ow I arge) com pi I e wi th n o warn i n gs or errors. M ake 
sure that the error-message level issetashigh as possible. In M icrosoft compilers, use 
either /W 3 or /W 4; with other compilers, use the equivalent. It can be done— I've 
written programs with hundreds of thousands of lines and no compiler messages. 



If you're not programming on an IBM PC (or other computer that uses the Intel 
segmented architecture), skip this part of this chapter. You have enough to fill your 
head without having to add the information in this section. 

ThePC, when running in real mode,isabletoaddressonly64K atanytimeusing 
16-bit addresses, referred to asnear pointers. T hislimitation isa problem becausemany 
programsand their data arelarger than 64K . T o addressmorethan 64K , it is necessary 
to use segments and offsets, which areformsof 24-bit addresses. I f thecompiler istold 
to use segments, it generally creates two problems: Segment arithmetic will causeyour 
application to be slightly slower, and the size of the program will be larger. U sing 
segments and offsets is referred to as far pointers. Because you can choose to use far 
pointers for function calls, or for data references or both, therearefour combinations 
of models, as shown in Table 1.5. 



Memory Models 
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Table 1.5. PC segmented architecture models. 
Model Addressing Used 

Small N ear addresses for both data and function calls, where functions 
and data each have one segment allocated to them. 

Compact N ear pointers for the function calls and far pointers for data; 

used for small programs that use large amounts of data memory. 

M edium Far pointers for the function calls and near pointers for data; for 
larger programs that don't have more than 64K of data allocated. 

Large Far pointers for the function calls and far pointers for data; for 
larger programs that have more than 64K of data allocated. 



On the positive side, using a memory model larger than necessary isn't always a 
serious problem. The size of the program often isn't increased much (less than 10 
percent), and the differences in execution speed may be slight. It is possible to 
benchmark your compiler and determinetheexecution times and executableprogram 
size differences. 



When in doubt, use the large model when you are writing your 
applications. Using this model enables you to develop any size 
program. If you find later that the program wasn't as large as you 
expected, you can change to one of the other models and not have to change 
compiler memory models in the middle of the project. 




Summary 

In this chapter, you learned about subjects that will assist you in writing better C 
programs: 

• The history of theC language, and the AN SI standard. 

• Programming style, and commenting and formatting your source code. 

• T he use of the PC 's memory models; how and why to select a specific memory 
model. 
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You probably couldn't write anything except the simplest program without arrays. 
H aving worked with programming languages that don't support arrays, I know how 
difficult it can be to create meaningful applications using only singular variables 

TheC language provides programmers with an additional tool to access mem- 
ory, for both arrays and singular variables. This method, using pointers, seldom is 
found in higher-level languages, which often "protect" the programmer from direct 
memory manipulation. 

With pointers, you use the technique of indirection, which is the method of 
obtaining thevalue of the memory object to which the pointer is pointing. 



Pointers, Indirection, and Arrays 

The concept of pointers, indirection, and arrays is an advanced idea. You can write 
programs (very good programs) without using pointers or indirection, and you can 
write good programs using only direct array accessing, without using pointers or 
indirection. Let's look at each— pointers, indirection, and arrays. 
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Pointers 

A poi nter isa variable(or constant) that containstheaddress (in memory) of a specific 
object. It hasthefollowing qualities: 

1. A pointer can hold the address of any valid data object, including an array, a 
singular variable, a structure, and a union. 

2. A pointer can hold the address of a function. 

3. A pointer cannot hold the address of a constant, with one possible exception: A 
string constant has an address, which can be stored in a pointer variable 
indirectly (usually as the result of being passed as a function call parameter). 

Pointers enable you to access any block of memory you want, but there are 
restrictions, of course: 

• You must have the operating system's permission to access the memory (the 
memory accessed must have been allocated to your program). 

• You must know where the block of memory you want to access is located. For 
many applications, knowing this information is easy because the memory will 
have been allocated for the program, and the program will have been given the 
address of the memory. I f the memory is a common block, such as a video 
buffer, either the memory will be found in a fixed location or a pointer to the 
memory will be found in a known location. 

Let's review theC address of operator &. To obtain the address of a singular 
variableand an array, orthedement in an array, simply prefix thevariable's name with 
the& operator. This section has several examples of using the& operator. 

W hen you use pointers, you must tell the compiler the size of the object the 
pointer will be used with. W hat does size have to do with it? If a pointer variable can 
pointtoonlyonethingatatime, whydoyou haveto tell thecompiler that thevariable 
isa pointer to typechar , or type i nt ? I f you remember that a pointer variablecan be 
modified, you begin to get the idea that there is nothing wrong with incrementing a 
pointer, adding to its value, or decrementing it. Becauseachar is an 8-bit-wide value 
(1 byte), an i nt isa 16-bit-wide value (2 bytes), and ai ong isa 32-bit-wide value 
(4 bytes), the compiler must know how many bytes are between the data objects to 
which the pointer will point. 
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F igure 3.1 shows how the memory for both the integer array and a pointer to a 
vari abl e of type i n t typi cal I y i s al I ocated . T h e f i gu re sh ows al so th e mem ory al I ocated 
to s z st r i n g and the pointer to a variable of type c h a r . 

Address: 0 1 2 3 4 5 6 7 

int nArray[5]; 



charszString[12]; 

int "pnArray; 

char "pszString; — 



Note: This example assumes that the size of an int is 2 bytes, and that 
the size of a pointer is 2 bytes. 

Figure 3.1. char and int pointers to arrays. 

Always remember that when a pointer is incremented, its value is increased by 
thesi zeof ( ) thepointer'stype. When a pointer is decremented, itsvalueisdecreased 
by thesi zeof ( i thepointer'stype. 

You use thepointer declaration typemodifier to tell thecompiler that a variable 
will bea pointer to a variabletype rather than being that variable type. Let's look at 
some identifiers, both variables that hold data and pointer variables: 

int nCount er =0; 
int *pnCounter; 

pnCount er = &nCount er ; 

Two variables have been created in this code fragment. The first, an i nt called 
ncounter , holds a simple counter that your program may use. The second variable, 
pncounter ,hastheaddressof ncounter assigned to it. Thisassignment could havebeen 
done as an initialization also. 

Notice that both thepointer and thevariablewhose address will be stored in it 
have similar names. This naming is important when you need someway to know the 
purpose of thepointer. If you had named the pointer p po i nter , you wouldn't know 
its purpose. 



+00 
+08 
+10 
+18 
+20 
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T wo vari abl es are al I ocated agai n in thefollowing linesof code. First, a character 
string called szstri ng iscreated (and initialized) and then a pointer to that string is 
created. 

char szStri ng[20] = {"This is a string."}; 
char * pszSt r i ng; 

pszString = szString; 
pszSt r i ng = &szStri ng; 
pszString = & s z S t r i ng[ 0] ; 

I n all threeof thefollowing assignment statements, p s z s t r i n g containsthesame 
valueand alwayscontainsapointertothefi rstcharacter inszst r i ng .Subtledifferences 
exist in these assignments, however. 

pszString = szString; 
pszString = & s z S t r i ng; 
pszString = &szSt r i ng[ 0] ; 

T hefirst assignment assignstheaddressof thearray to ps z string. T hisyieldsthe 
addressof thefirst element in thearray. 

In the second statement, the compiler assigns the address of the array to 
pszst r i ng. Generally, thisalsoyieldstheaddressof thefirst element in thearray. The 
primary difference is that, with an array of morethan onedimension, you can havethe 
C compiler take care of indexing. 

Thethird statement hasa pointer to thespecified element in thearray (or string). 
Somecompilers(notall of them) check to see whether thedement specified iswithin 
the bounds of the array; you should not count on the compiler to catch this error, 
however. 

H ere'sa difficult issue: An array nameisnot a pointer, but an array namecan be 
assigned to a pointer variable to create a pointer to the array, it can be passed to a 
function as though it is a pointer to the array, and so on. I've had few problems 
consideringthenameofan array asapointertothefirstdementin thearray; however, 
only experience (and the compiler, I hope) can tdl when this is not true. 
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Indirection 

Now that you havea pointer, what doyou do with it?Becauseit'spart of your program, 
you can't writeyour address on it and nail it to a tree so that your friend scan find your 
home. You can, however, assign to a pointer the address of a variable and passittoa 
function, and then the function can find and use the variable (just as some of your 
friends might find and use your home). 

TheC operator* is called the indirection operator. It tells C to use whatever the 
pointer variable is pointing to and use the value contained in the memory that the 
pointer is pointing to. 

An Example of Pointers, Indirection, 
and Arrays 

It took a whileformeto understand the relation ship between pointers and indirection 
(and arrays), but tables, pictures, and example programs can help you understand it 
too. The program in Listing 3.1 is a useless program. It does nothing except assign 
values to variables and test the values and addresses of the variables. 

Listing 3.1. POINTERS. C. 

/* POINTERS, written 20 May 1 9 9 2 by Peter D. Hipson */ 
/* Demonstration of pointers and indirection. */ 

# i n c I u d e <stdio.h> // Make includes first part of file 

# i n c I u d e <string.h> // For string functions. 

int main(void); // Define ma i n ( ) and the fact that this program doesn't 
/ / use any passed pa r a met er s . 

int ma i n ( ) 
{ 

continues 
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Listing 3.1. continued 

int nCounter =33; 

int * p nCo u n t e r = (int * ) NULL; 

char s z S a y i n g [ ] ={ 

"Firestone's Law of Forecasti ng: \ n" 

Chicken Little only has to be right once. \ n \ n"}; 

char * psz Say i ng = (char * ) NULL; 

pri n t f ( 

"nCounter | pnCounter | *( pnCounter ) | pszSaying | " 
"szSayi ng[0] | s z S a y i n g [ 0 - 2 0 ] \ n " ) ; 

pri n t f ( " %8 d | %8p | %8d | %8p | %c | %2 0 . 2 0 s \ n " , 

nCounter, 
pnCounter, 
* ( pnCounter) , 
pszSayi ng, 
*( pszSayi ng) , 
szSayi ng) ; 

pri n t f ( " pnCounter = & n C o u n t e r ; \n"); 
pnCounter = &n Counter; 

pri n t f ( " %8 d | %8p | %8d | %8p | %c | %2 0.2 0s\n", 

nCounter, 
pnCounter, 
* ( pnCounter) , 
pszSayi ng, 
*( pszSayi ng) , 
szSayi ng) ; 

pri ntf("pszSayi ng = s z S a y i n g ; \ n " ) ; 
pszSayi ng = szSayi ng; 

pri n t f ( " %8 d | %8p | %8d | %8p | %c | %2 0 . 2 Os \ n " , 

nCounter, 
pnCounter, 
* ( pnCounter) , 
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pszSayi ng, 
*( pszSayi ng) , 
szSayi ng) ; 



pri ntf( "pszSayi ng = &sz Saying; \n"); 

pszSaying = &s z S a y i n g ; // Different levels of indirection! 

/ / A cast (char * ) will wo r k here. 



pri n t f ( " %8 d | %8p | %8d | %8p | %c | %2 0 . 2 0 s \ n " , 

n Co u n t e r , 
pnCounter, 
* ( pnCounter) , 
pszSayi ng, 
*( pszSayi ng) , 
szSayi ng) ; 

pri ntf( "pszSayi ng = &s z S a y i ng[ 0] ; \n"); 
pszSaying = &szSayi ng[ 0] ; 



pri n t f ( " %8 d | %8p | %8d | %8p | %c | %2 0 . 2 0 s \ n " 

n Co u n t e r , 
pnCounter, 
* ( pnCounter) , 
pszSayi ng, 
*( pszSayi ng) , 
szSayi ng) ; 



pri ntf("*(pnCounter) = 12 3 4; \ n " ) ; 
* ( pnCount er ) = 1 2 3 4; 



pri n t f ( " %8 d | %8p | %8d | %8p | %c | %2 0 . 2 0 s \ n " 

n Co u n t e r , 
pnCounter, 
*( pnCounter) , 
pszSayi ng, 
*( pszSayi ng) , 
szSayi ng) ; 



return ( 0) ; 

} 
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Running PO INTERS. C in Listing 3.1 produces the output shown in Listing 
3.2. This output shows what happens when each of the pointer variables is modified 
and as the value pointed to by pncounter ischanged using the pointer. 



Listing 3.2. The output from POINTERS.C. 



nCounter pnCount er * 


(pnCounter) 


pszSaying 


szSayi ng[ 0] 


szSayi ng[ 0- 20] 








3 3 0000 


0 


0 0 0 0 




Firestone's Law of F 








pnCount er = &nCount er ; 








33 | 24F6 


33 


| 0 0 0 0 


| 


Firestone's Law of F 








pszSaying = szSaying; 








33 | 24F6 


33 


24A6 


F 


Firestone's Law of F 








pszSaying = StSzSayi ng; 








33 | 24F6 


33 


24A6 


F 


Firestone's Law of F 








pszSaying = &szSayi ng[ 0] 








33 | 24F6 


33 


24A6 


F 


Firestone's Law of F 








*( pnCount er ) = 1 2 3 4; 








1234 | 24F6 


1234 


24A6 


F 


Firestone's Law of F 









Pointersaremost commonly used when acalled function must modifyavari able. 
This process usually happens when a function returns two different values and 
thereforecannotusenormalfunction-valuereturning mechanisms. A pointer ispassed 
to a variable, and thecalled function changes thecontentsofthevariables as required 
(see Listing 3.3). I n Listing 3.3, AD D ER.C , a function is called to add two numbers, 
and the result is placed in the third. This function then returns TRU E if the two 
numbers fit in the sum, or false if overflow occurs. 

Listing 3.3. ADDER. C. 

/* ADDER, written 20 May 1 99 2 by Peter D. Hipson */ 
/* Calling functions with passed pointers. */ 
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tinclude < s t d i o . h > // Make includes first part of file 

# i n c I u d e <string.h> // For string functions. 

#i nc I ude <limits.h> / / For integer value limits. 



#define TRUE 1 
#define FALSE 0 



int main(void); // Define ma i n ( ) and the fact that this program doesn't 
/ / use any passed pa r a met er s . 

int D o A d d ( i n t * nResult, int nFirstValue, int nSecondVal ue) ; 



int ma i n ( ) 



{ 



nt n F i r st = 3 0 0 0 

nt nSecond = 700 
n t n S u m = 0 



pr i ntf (" BEFORE: nSum = %4d nFirst = %4d nSecond = %4d\n", 
n S u m, 
n F i r s t , 
nSecond) ; 



if ( ! Do A d d ( &nSum, nFirst, nSecond)) 
{ 

p r i n t f ( " %d + %d don't fit in an i n t \ n " , 
n F i r s t , 
nSecond) ; 

} 



p r i n t f ( " A F T E R : n S u m = %4 d nFirst = %4 d nSecond = %4 d \ n " , 
n S u m, 
n F i r s t , 
nSecond) ; 

return ( 0) ; 

} 

continues 
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Listing 3.3. continued 

i nt DoAd d ( 

i n t * n Res u I t , 
i nt nFi rstVal ue, 
i nt nSecond Value) 



if ( ( I ong) nFi rstVal ue + ( I ong) nSecondVal ue > ( I o ng ) I NT_ MAX) 
{ 

r et ur n( FALSE) ; 

} 

else 

{ 

* n R e s u I t = nFi rstVal ue + nSecondVal ue; 

} 

return(TRUE) ; 

} 



You should notice two interesting things aboutADDER.C: 

1. Thefunction is called with a pointer to an integer that will receive the results 
of the addition. Also, before the numbers are summed, theprogram checks to 
makesure that theresults will fit in an i nt without overflow. I f the result 
doesn't fit, the numbers are not summed and thefunction returns FALSE, if 
the result fits, the sum is saved at the address pointed to by n Res u 1 1 , and the 
function returnsTRU E. 

2. The test is made using casts to type i ong because the result of adding two 
shorts can never be larger than a i ong. You cannot use i n t types here because 
thetest isn't meaningful if an overflow occurs. 

RunningAD D ER.C with both nFi r st and nSecond settoalargevalue(30,000, 
for example) shows how thetest for overflow works. 

Character Arrays and Strings 

C stores stri n gs as arrays of type char . Notethat no operators work on stringsdirectly. 
You cannot copy a string using the assignment (equal sign) operator, nor can you 
com pare two strings using logical operators. 
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T o m ake u p f or th e sh ortcom ings in C 's ch aracter han d I i n g, a I arge n u m ber of 
string functions are in the standard library (see Chapter 14, "ANSI C Library 
Functions"). Because the particular functionality your application requires might not 
be present in oneof theC library functions, you can write a function to do whatever 
you want. 

Thissection doesn't show you howtocountwordsinastring(thedemo program 
does that), but it does show you how easy it is to work with strings and manipulate 
pointers to strings. 

By now, you should not still be writing programs that compare strings using 
logical operators, as in thefollowing example: 

char s z F i r s t [ ] = {"This is a string"}; 
char s z N e x t [ ] = {"Before this one"); 

if ( s z F i r s t > s z Next ) 

{ 

/ * the test was meani ngl ess ! */ 

} 

This comparison simply evaluates the addresses of the two strings, not their 
contents. The result of the test is undefined because you cannot predict where in 
memory the strings will be located, nor are their contents related to their memory 
address. 

T hecorrect way to compare two strings is to call the library function s t r c mp ( ) , 
which returns a value based on the logical relationship between the two strings: 

char s z F i r s t [ ] = {"This is a string"}; 
char s z N e x t [ ] = {"Before this one"); 

if (strcmp(szFirst, szNext) >0) 

{ 

/* szFirst is before szNext! */ 

} 

This relationship is much more useful to your programs than are the string's 
addresses. N U M WO RD .C countsthenumberof wordsin asentencethatareentered 
from the keyboard (see Listing 3.4). 
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Listing 3.4. NUMWORD.C. 

/* NUMWORD, written 20 May 1 9 9 2 by Peter D. Hipson */ 
/* Program to count words in sentences. */ 

#i n c I u d e <stdio.h> // Make includes first part of file 
#include <string.h> // For string functions 

#define TRUE 1 

#define FALSE 0 

int main (void); // Define ma i n ( ) and the fact that this program doesn't 

/ / use any passed pa r a met er s . 



int NumberWords( char * pString); 

tdefine Bl GESTLI NE 2 5 6 /* The biggest line readable from keyboard */ 

/* Though these variables are defined as external, they can be 

* defined inside the function or be allocated dynamically, 

* depending on the program's needs and the amount of memory available */ 



char szl nput [ Bl GEST LI NE] ; 

int ma i n ( ) 

{ 

int i ; 

p r i n t f ( 

"Enter lines, when last one is entered\n" 
"provide a End- Of- File (ctrl-Z on most systems)\n" 
"to end the program. \ n\ n"); 

while ( g et s ( s z I n put ) ) 

{ 
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p r i n t f ( " Wo r d s = %2 d ' %. 5 0 s ' \ n " , 
NumberWords(szl nput), 
s z I nput) ; 

} 

p r i n t f ( " \ n " ) ; 
return ( 0) ; 

} 

i n t N u mb e r Wo r d s ( 
char szSt r i ng[ ] ) 

{ 

i nt i ; 

i nt n B I a n k = TRUE; 

int nCount = 0; 

for ( i =0; s zSt r i ng [ i ] ; i + + ) 
{ 

i f ( szSt ri n g [ i ] ! = ' ' ) 

{ 

if ( n B I a n k ) 

{ 

++nCount ; 

} 

n B I a n k = FALSE; 

} 

else 

{ 

n B I a n k = TRUE; 

} 

} 

r et ur n( nCount ) ; 

} 
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NUMWORD has a very simple loop that calls gets) ) until the end-of-file is 
reached. After gets ( ) returns, the loop itself callspri ntf ( ) , which has as one of its 
parameters a call to theNu mber wo r ds ( ) function. 

pri ntf("Words = %2d ' %. 5 0 s ' \ n " , 
NumberWords(szl nput) , 
s z I nput) ; 

C first callsN umber wordsi ) and then passestopr i ntf o thereturned value, along 
with the other parameters. 

for ( i =0; szSt r i ng[ i ] ; i ++) 
{ 

if ( szSt r i ng[ i ] ! = ' ' ) 
{ 

if ( n B I a n k ) 

{ 

++nCount ; 

} 

n B I a n k = FALSE; 

} 

else 

{ 

n B I a n k = TRUE; 

} 

} 

nu mber wo r ds ( ) hasa loop that looksat thepassed string and parsesout thewords. 
T he format for this loop is a f o r ( ) loop; wh i i e ( ) can be used, however. This loop 
movesthrough th e character str i n g an d incrementsan indexto thepassed string. W hen 
the loop starts, it is assumed that a blank has been encountered already. This 
assumption ismadeby setting theblank flag (n b i a nk) on so that you can count thefirst 
word regardless of whether it's preceded by blanks. Also, theword count (ncount ) is 
set to zero, which indicates that no words have been counted. 

W hen thefirst nonblank character isfound, theword counter is incremented (a 
word has been found), and theblank flag isturned off. Theloop continues searching 
for the next blank; when it isfound, theblank flag isset to on andtheprocesscontinues 
until theend of the string isfound. 
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I ndirection to Access Character Strings 



To change NUMWORD to use indirection to access the string, the loop in 
n u mb e r wo r d s ( ) must change slightly (see Listing 3.5). 

L isting 3.5. NUMWORD1.C. 

/* NUMW0RD1, written 21 May 1 9 9 2 by Peter D. Hipson */ 
/* Program to count words in sentences. */ 

tinclude <stdio.h> // Make includes first part of file 
tinclude <string.h> // For string functions 

#define TRUE 1 
tdefine FALSE 0 

int main(void); // Define ma i n ( ) and the fact that this program doesn't 



#define Bl GESTLI NE 2 5 6 /* The biggest line readable from keyboard */ 

/* Although these variables are defined as external, they can be 

* defined inside the function or be allocated dynamically, 

* depending on the program's needs and memory available. */ 

char szl nput[ Bl GEST LI NE] ; 

int ma i n ( ) 

{ 

int i ; 



/ / use any passed pa r a met er s . 



i nt 



N u mb e r Wo r d s ( char 



* pSt r i ng) ; 



p r i nt f ( 



continues 
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Listing 3.5. continued 

"Enter lines, when last one is entered\n" 
"provide a End- Of- File (ctrl-Z on most systems)\n" 
"to end the program. \ n\ n"); 

while ( g et s ( s z I n put ) ) 

{ 

p r i n t f ( " Wo r d s = %2 d ' %. 5 0 s ' \ n " , 
N u mb e r Wo r d s ( s z I n p u t ) , 
szl nput ) ; 

} 

p r i n t f ( " \ n " ) ; 
return ( 0) ; 

} 

i n t N u mb e r Wo r d s ( 
char * pSt r i ng) 



i nt n B I a n k = TRUE; 

int nCount = 0; 

do 
{ 

if ( *( pSt r i ng) && *( pSt r i ng) ! = 

{ 

if ( n B I a n k ) 

{ 

++nCount ; 

} 

n B I a n k = FALSE; 

} 

else 

{ 

n B I a n k = TRUE; 

} 
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} wh i I e ( * ( pS t r i n g + + ) ) ; 
return(nCount); 

} 



Number wordsi ) again hasa loop that looksat thepassed string and parsesoutthe 
words. Theformat for this loop isdo( ) . . . wh ; i e( ) .A straight whi i en ore/en at or ( ) 
loop, however, can be used: 

do 
{ 

if ( *( pSt r i ng) && *( pSt r i ng) ! = ' ' ) 

{ 

if ( n B I a n k ) 

{ 

++nCount ; 

} 

n B I a n k = FALSE; 

} 

else 

{ 

n B I a n k = TRUE; 

} 

} whi I e( * ( pSt r i ng++) ) ; 

You no longer need to use an index variable, because you are using the pointer 
that was passed to keep track of where you are in the string. One possible advantage 
to this method isthat by incrementing thepoi nter rather than an index to a string, the 
function generally is both faster and smaller. 

Thisloop moves through thecharacter string and increments thepassed pointer. 
Remember that this passed pointer is a private copy for this function and can be 
modified. Itisassumedthatablankhas been encountered already, bysettingtheblank 
flag on so that you can count the first word regardless of whether it is preceded by 
blanks. Also, theword count isset to zero so that no wordsarecounted. W hen thefirst 
nonblank character isfound,theword counter is incremented (a word hasbeen found) 
and theblank flag isturned off. Theloop continues searching for thenext blank; when 
it isfound, theblankflag issettoon and theprocesscontinuesuntil theend of thestring 
is found. 
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Listing 3.6 shows the assembly listing for theversion of Number words ( ) that uses 
pointer indexing. The compiler produces this machine code, commented with the 
original source lines, when thefunction is compiled. 

Listing 3.6. NUM WORD3.COD, theassembly listing for the pointer 
version of NumberWordsO. 

; Edited for size. 

; Static Name Aliases 

TITLE n u mwo r d 3 . c 
NAME n u mwo r d 3 

. 80 8 7 



TEXT 


SEGMENT 


WORD PUBLIC ' 


CODE' 


TEXT 


ENDS 






_ DATA 


SEGMENT 


WORD PUBLIC ' 


DATA' 


_ DATA 


ENDS 






CONST 


SEGMENT 


WORD PUBLIC ' 


CONST' 


CONST 


ENDS 






BSS 


SEGMENT 


WORD PUBLIC 'BSS' 


BSS 


ENDS 






DGROUP 


GROUP 


CONST, BSS, 


_ DATA 



ASSUME CS: TEXT, DS: DGROUP, SS: DGROUP 
EXTRN - - ac r t us ed : ABS 
EXTRN - - chkst k: NEAR 

_ T E X T SEGMENT 

ASSUME CS: TEXT 
;|*** /* NUMWORD3, written 21 May 1 9 9 2 by Peter D. Hipson */ 

. I * * * 

;|*** #include <stdio.h> // Make includes first part of file 

;|*** #include <string.h> // For string functions 

. I * * * 

; | *** #def i ne TRUE 1 

; | *** #def i ne FALSE 0 

. I * * * 
. I * * * 

;|*** int Number Wo r d s ( c h a r * pString); 

. I * * * 

; | * * * int Nu mbe r Wo r d s ( 
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I * * * char 
| * * * 
| * * * { 
Line 15 
PUBLIC 
Number Wor ds 

000000 
000001 
000003 
000006 
p S t r i n g = 
n B I a n k = - 
nCount = - 

* * * 



* * * 

* * * 

* * * 

* * * 



pSt r i ng) 



N u mb e r Wo r d s 
P ROC NEAR 
55 

8b ec 
b8 06 00 
e8 00 00 

4 
2 
4 



push 
mo v 
mo v 
call 



bp 

bp, s p 
a x , 6 

chkst k 



* * * i n t n B 


lank 


- T D 1 1 P • 

- 1 K U L , 






Line 17 










*** 000009 


C7 


4 0 t e u i 


U U 


ITIO V vvUK U r 1 K [Dp 


Blank 










* * * i n t n Co u nt 


= 0 ; 






Li ne 18 










*** OOOOOe 


c7 


46 fc 00 


00 


mov WORD PTR [bp 


Count 










* * * 










^ ^ ^ do 










Li ne 20 




$ D2 3 9 : 






* * * | 










Line 21 










$ $ $ j ^ 


(*( 


pSt r i ng) 


&& * 


pStri ng) ! = ' ' ) 


Li ne 22 










*** 000013 


8b 


5e 04 




mov bx, WORD PTR [ bp +4] 


*** 000016 


8a 


07 




mov al , BYTE PTR [ bx] 


*** 000018 


88 


46 fa 




mov BYTE PTR [ bp- 6] , al 


*** 00001b 


Oa 


cO 




or a 1 , a 1 


*** OOOOld 


74 


15 




j e $1242 


*** OOOOlf 


3c 


20 




c mp a 1 , 3 2 


*** 000021 


74 


11 




j e $1242 


* * * | 










Line 23 










* * * 


i f 


( n Bl a n k ) 







pSt r i ng 



continues 
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Listing 3.6. continued 



Line 

* * * 

* * * 

* * * 

Line 

* * * 

Line 

* * * 

* * * 



24 
000023 
000027 

25 

26 
000029 



Line 27 



| * * * 
| * * * 
Line 

* * * 

n B I a n k 

| * * * 

Line 

| * * * 

Line 

* * * 

* * * 

| * * * 

Line 

| * * * 

Line 

* * * 

n B I a n k 



} 



29 
00002c 

30 

31 
000031 
000033 



32 

33 
000034 



83 7e fe 00 
7 4 0 3 

{ 

++nCount ; 

ff 46 fc 

} 



n B I a n k = FALSE; 

$12 4 3: 
c7 46 fe 00 00 



cmp WORD PTR [ bp-2] , 0 
e $1243 



n B I a n k 



i nc 



WORD PTR [ bp- 4] 



nCo u n t 



mo v 



WORD PTR [ bp- 2] , 0 



else 



eb 06 
90 

$12 4 2: 



mp 



SHORT $1244 



nop 



n B I ank = TRUE; 
c7 46 fe 01 00 



mo v 



WORD PTR [ bp- 2] , 1 



Line 34 



* * * 

* * * 

Line 

* * * 

* * * 

* * * 

* * * 



} 

$12 4 4: 

} wh i I e ( * ( pSt r i n g + + ) ) ; 



36 
000039 
00003c 
0 0 00 3 f 
000042 



8b 5e 04 

ff 46 04 

80 3f 00 

75 cf 



mov 
i nc 
c mp 
i ne 



bx, WORD PTR [ bp+4] ; pSt r i ng 
WORD PTR [bp+4] ; pSt r i ng 
BYTE PTR [ bx] , 0 
$ D2 3 9 
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I * * * 



r et u 



r n 



( nCount ) ; 



Li ne 38 



*** 000044 

*** 000047 

*** 000049 

*** 00004a 

*** 00004b 



8b 46 fc 
8b e5 



mo v 



mo v 



ax, WORD PTR [ bp- 4] 
s p, b p 



; n Co u n t 



5d 
c3 
90 



pop 
ret 



nop 



bp 



_ N u mb e r Wo r d s 

TEXT ENDS 
END 

. | * * * j 



ENDP 



Listing 3.7 is the assembly listing for the version of Numberwordsi ) that uses an 
index to the passed array. As in the preceding example, the compiler produces this 
machine code, commented with the original source lines, when the function is 
compiled. 

L isti ng 3.7. NUMWORD4.COD, theassembly listingfor thearray 
indexed version of NumberWordsO. 

; Edited for size. 

; Static Name Aliases 

TITLE numwor d 4 . c 
NAME numword4 

. 8 0 8 7 



TEXT 


SEGMENT 


WORD PUBLIC ' 


CODE' 


TEXT 


ENDS 






_ DATA 


SEGMENT 


WORD PUBLIC ' 


DATA' 


_ DATA 


ENDS 






CONST 


SEGMENT 


WORD PUBLI C ' 


CONST' 


CONST 


ENDS 






BSS 


SEGMENT 


WORD PUBLIC 'BSS' 


_ BSS 


ENDS 






DGROUP 


GROUP 


CONST, BSS, 


_ DATA 



ASSUME CS: _ T E X T , DS: DGROUP, SS: DGROUP 



continues 
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Listing 3.7. continued 



EXTRN --acrtused: ABS 
EXTRN - - c hkst k: NEAR 
_ T E X T SEGMENT 

ASSUME CS: TEXT 

*** /* NUMWORD, written 20 May 1 9 9 2 by Peter D. Hipson */ 

* * * 

*** #include <stdio.h> // Make includes first part of file 

*** #include <string.h> // For string functions 



* * * 



| * * * #d ef i n e 


TRUE 1 




| * * * #d ef i n e 


FALSE 0 




1 if. if if. 






1 if if if 






\ if if if j p| |- 


N u mb e r Wo r d s ( c h a r 


* pSt r i ng ) ; 


1 if if if 






1 if if if 






\ if if if j p| |- 


N u mb e r Wo r d s ( 




| * * * char 


szSt r i ng[ ] ) 




1 * * * 






1 * * * | 






Line 16 






PUBLI C 


_ N u mb e r Wo r d s 




NumberWords 


PROC NEAR 




*** 000000 


55 


push bp 


*** 000001 


8b ec 


mo v b p , s p 


*** 000003 


b8 08 00 


mov a x , 8 


*** 000006 


e8 00 00 


call - - chkst k 


*** 000009 


56 


push si 


s z S t r i n g 


= 4 




i = - 6 






n B 1 a n k = 


- 2 




n C o u n t = 


• 4 




* * * 






| * * * i n t 


i ; 




| * * * i n t 


n B 1 a n k = TRUE; 





Li ne 19 
*** 00000a 
n B I ank 

I * * * i n t n Co u n t 



c7 46 fe 01 00 
0; 



mo v 



WORD PTR [ bp- 2] , 1 
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Li ne 

* * * 

n Co u n t 

| * * * 
| * * * 

Li ne 

* * * 

* * * 

* * * 



20 
OOOOOf 



for ( i 

22 
000014 
000019 
00001b 



c7 46 fc 00 00 



= 0; szStri ng[i ]; i ++) 

c7 46 fa 00 00 
eb 09 j mp 

90 nop 
$12 4 3: 



| * * * 

| * * * 

| * * * 

| * * * 

| * * * 

| * * * 

| * * * 

| * * * 

| * * * 

| * * * 

| * * * 

| * * * 

Li ne 

| * * * 

Li ne 

* * * 

n Bl a n k 

| * * * 

Li ne 

| * * * 

Li ne 



{ 



f (szStri ng[ i ] ! = ' ' ) 



{ 



34 

35 
00001c 



36 



} 



* * * 

* * * 

* * * 

* * * 

* * * 

* * * 



37 

000021 

000024 
000027 
00002a 
00002c 
0 0 0 0 2 f 
000031 



if ( n B I a n k ) 
{ 



+ + n C o u nt ; 



n B I a n k = FALSE; 



} 

el se 

{ 



n B I a n k = TRUE; 
c7 46 fe 01 00 



} 



$ F C 2 4 1 : 
ff 46 fa 

$ F 2 4 0 : 
8b 5e fa 
8b 76 04 
8a 00 
88 46 f8 
Oa cO 
74 15 



i nc 

mo v 
mo v 

mo v 
mo v 

o r 

j e 



mo v 



WORD PTR [ bp- 4] , 0 



mov WORD PTR [ bp- 6] , 0 
SHORT $ F 2 4 0 



mo v 



WORD PTR [ bp- 2] , 1 



WORD PTR [ bp- 6] 

bx, WORD PTR [ bp- 6] 
s i , WORD PTR [ bp+4] 

al , [ bx] [ si ] 
BYTE PTR [ bp- 8] , al 
a I , a I 
$ F B 2 4 2 



; i 

; sz St r i ng 



continues 
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Listing 3.7. continued 



* * * 

Line 23 

* * * 

Li ne 24 
*** 000033 
*** 000035 

* * * | 

Line 25 

* * * 

Line 26 
*** 000037 
*** 00003b 

* * * 

Line 27 

* * * 

Li ne 28 

*** 00003d 

* * * 

Li ne 29 

* * * 

* * * 

Line 31 



n B I 

* * 

Li 

* * 



*** 000040 
a n k 

* 

ne 32 
ne 33 

*** 000045 
*** 000047 



if ( szSt r i ng[ i ] ! 

3c 20 
74 e5 



if ( n B I a n k ) 

83 7e fe 00 

7 4 0 3 

{ 

+ + n Co u n t ; 

ff 46 fc 

} 



n B I a n k = FALSE; 

$12 4 4: 
c7 46 fe 00 00 



} 

else 



* * > 

* * > 

* * > 

* * > 

* * t 



eb da 
90 

$ F B 2 4 2 : 
n B I a n k = TRUE; 



c mp a I , 3 2 
j e $1243 



cmp WORD PTR [ bp-2] , 0 
e $1244 



n B I a n k 



nc 



WORD PTR [ bp- 4] 



n C o u n t 



mo v 



WORD PTR [ bp- 2] , 0 



mp 



SHORT $ F C 2 4 1 



nop 
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mo v ax.WORD PTR [bp-4] ; n C o u n t 
pop si 

mo v s p , b p 
pop bp 
ret 

_ Number Words ENDP 

TEXT ENDS 
END 

I | * * * j 



return! n Co u n t ) 



Li ne 39 



* * * 

* * * 

* * * 

* * * 

* * * 



000048 
00004b 
00004c 
00004e 
00004f 



8b 46 fc 
5e 

8b e5 

5d 

c3 



The assembly listings show the major differences from what the original C 
version shows; you should consider several factors, however, when you are deciding 
whether to use indexing or to modify pointers: 

• Functionsthat useindexing often are easier to read and understand. 

• Functionsthat useindexing often generate more machine code than functions 
that use pointer modification. This situation is more prevalent in functions 
that have many references to the variable (or variables) accessed with pointers. 

• Functionsthat useindexing often areslowerthan functionsthat use pointer 
modification. This situation is more prevalent in functionsthat have many 
references to thevariable (or variables) accessed with pointers, and occurs 
because the functions usually must add the index to the array base for each 
access. 

• Functions with array indexing requirelocal variables that require stack space. 
This consideration usually is a minor one, but it may be a factor when stack 
usagemust be either minimized or eliminated. 

You should note that even though theexample program used a string (which is 
a character array), theconceptsarethesamein other arrays, such asi nt ,i o n g , ort i oat . 
The important thing with nonstring arrays is that the function the string is being 
passed to must know how many elements are found in thearray, because only strings 
have a meaningful end marker, null . 
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Protecting Strings in Memory 

If I could find a way to protect strings in memory, I would be rich. Seriously, theonly 
thing that protects strings in memory is careful programming. Although many 
operating environments offer someformsof memory protection and somecompilers 
offer bounds checking, this protection is limited and easily circumvented— often 
unknowingly by programmers. 

A number of dangerous functions in theC language's library don't know how 
long astring isand easily can overwri te a stri n g's memory al I ocati on wi th ou t n oti fyi n g 
the programmer. Even functions that tell you how much of the string they used have 
possibly already destroyed valuablememory when they writepasttheend of thestring. 

Two of the worst offenders are input/output functions and the various string 
functions. Theinput/outputfunctionsareoften given a buffer in order to read in the 
desired information. The problem is that they don't know how long the buffer is. In 
the following example fragment, the programmer made the assumption that a user 
never would enter a line longer than 80 characters: 

char szBuffer[ 80] ; // You'll never read more than 80 characters 
// (ha-ha) . 

if ( gets( szBuf f er) ) 
{ 

// Process the buffer inputted. 

} 

T heprogrammer might havethought, for example, that theterminal to beused 
allowed only 80 charactersper line. Theuser first used I/O redirection to provideinput 
totheprogram, though, and thelinesin theuser'sfilewere about 200 characters long. 
Of course, the program crashed. 

This problem doesn't really have a fix that always works. The fix most often 
consistsof putting a realistic maximum on thebuffer size, which meansthatthebuffer 
must becapableof holding a very large string. In thepreceding example, it would not 
beunreasonabletodefinetheinput buffer to be several thousand byteslong. I usually 
create i n my programs ageneric buffer (called s zTe mpBuf f er ), which isused for pi aces 
where I don't want to experience buffer overflow. 

In the following example, a set of two strings has been defined and then 
concatenated, when necessary. 
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char szMyName[] = {"Peter D. Hips on"); 
char s z My Ad d r e s s [ ] = {"New Hampshire"); 

// bFul I Addr ess says that the user wants my full address: 

i f ( bFul I Address) 

{ 

s t r c a t ( s z My Na me , s z My A d d r es s ) ; 

} 

The only problem is that s z My Na me is not large enough to hold both strings. 
Crash— it's over! Again, thefixisto be sure that the destination for the library string 
functionsislargeenough. OnepossiblefixistouseszTempBuf f er to hold theresult of 
the concatenation and then test to see whether it fits into thefinal destination, as in 
this example: 

s t r c py ( s z Te mp But f e r , szMyName); 
s t r c at ( s zTempBuf f er , s z My Ad d r es s ) ; 

if ( s t r I e n ( s z Te mp Buf f e r ) > s i z e of ( s z My Na me ) ) 
{ // Truncate the result to fit. 

s z Te mp Bu f f e r [ s i z eof ( s z My Na me ) - 1] = '\0'; 

pr i nt f ( " St r i ng ' %s ' won't fit into buff er \ n", s z Te mp Bu f f er ) ; 

} 

s t r c py ( s z My Na me , s zTe mp Buf f e r ) ; 

0 r if the preceding example doesn't require that the operation take place if the 
number of characters being assigned to a string doesn't fit, you can simply test and 
perform the operation if it fits: 

if ( s t r I e n ( s z My Na me) + s t r I e n ( s z My A d d r e s s ) < s i z eof ( s z My Na me ) ) 

{ 

s t r c a t ( s z My Na me, s z My Ad d r es s ) ; 

} 

el se 

{ 

pr i nt f ( " St r i ng '%s%s' won't fit into buffer! n", 
s z My Na me , 
s z My Ad d r ess) ; 

} 

T heprimary differenceisthat thefi rst examplecopies as many characters as will 
fit, and thesecond does not. For dther exampleto work, thecompiler must know how 
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I arge t h e stri n gs are. 1 t knowshow largewhen thestringsaredeclared in thesourcefile, 
or when they are defined with sizes Becauseyou often definearrays by specifying their 
size, you can get into trouble when an error message tells you thatthesizeof theobject 
is unknown. 

When you are using spri nto to print to a string, the function can cause 
innumerable problems because most format specifiers for floating-point numbers, 
when given an invalid value, print someratherstrangeresults. Often, you assumethat 
you r n u m bers are al ways correct; that assum pti on i s a weak on e, h owever, because th e 
majority of the numbers the program works with areprovided bytheuser. I n thiscase 
also, I try to use a large buffer, such as my szTempBuff er , to hold the results of 
spri ntf ( ) until I can besurethattheresulting string isnot too largefor theintended 
destination. 



Ragged-Right String Arrays 

There is a problem with using strings. Suppose that you have a program with a large 
number of strings, such as list of common sayings. Each lineof the sayings is placed 
in a string buffer. If these strings are used as constants (they won't be modified), you 
may wdl want to pack the strings together, with no wasted space. 

A morecommon way of storing strings is shown in theprogram FIXSTR.C. It 
allocates an array of 25 lines, each of which is 80 characters long. The total storage 
required for this array is 2,000 bytes (see Listing 3.8). 

Listing 3.8. FIXSTR.C. 

/* FIXSTR, written 20 May 1 9 9 2 by Peter D. Hipson */ 
/* Fixed-length strings in a program. */ 

#i n c I u d e < s t d i o . h > // Make includes first part of file 
#i n c I u d e <string.h> // For string functions. 

#def i ne MAX_LI NES 25 
#def i ne MAX_ LENGTH 80 

int main (void); // Define ma i n ( ) and the fact that this program doesn't 

/ / use any passed pa r a met er s . 
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i n t ma i n ( ) 
{ 

i nt i ; 

char szSayi ng[ MAX_ LI NES] [ MAX_ LENGTH] 



{ 



Firestone's Law of Forecasting:", 

Chicken Little only has to be right once.", 



Ma n I y ' s Max i m: " , 

Logic is a s y s t e ma t i c me t hod of coming to" 
the wrong conclusion with confidence.", 



Mo e r ' s truism:", 
The trouble with most jobs is the job holder's", 
resemblance to being one of a sled dog team. No one' 
gets a change of scenery except the lead dog.", 



Cannon's Co mme nt : " , 

If you tell the boss you were late for work because you", 
had a flat tire, the next morning you will have a flat tire. 



}; 



pri ntf ( 

"Number of lines is %d \ n" 
"size of item is %d \ n " 
"size of (char) is %d \ n " , 



s i z eof ( s z Say 
si zeof( szSay 
sizeof(szSay 



ng) / sizeof(szSaying[0]), // Number of elements. 
ng[ 0] ) , // Si ze of char * 

ng[ 0] [ 0] ) ) ; //Si ze of char 



s wi t c h ( s i z eof ( c ha r * ) ) 

{ 

case 2: // Near pointers 

pri ntf("Addr I e n s a y i n g \ n " ) 
break; 



continues 
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Listing 3.8. continued 

case 4: // Far pointers, 8 0 8 x segmented pointers, 
pr i ntf ( "Addr ess I en sayi ng\ n" ) ; 
break; 

} 

for (i = 0; i < si zeof ( szSayi ng) / s i zeof ( s zSay i ng [ 0] ) ; i ++) 

{ 

pri ntf ( "%p %3d ' %s ' \ n", 
szSayi n g [ i ] , 
strlen(szSaying[i]), 
szSayi ng[ i ]) ; 

} 

return ( 0) ; 



Figure 3.2 shows an example of how the memory for FIXSTR.C'sszSayi ng is 
allocated and used. In this program, sz say i ng is a single, two-dimensional character 
array. 



sz Sayings [ ] [ ]- 



^[0] 
[1] 
[2] 
[3] 
[4] 
[5] 
[6] 
[7] 
[ 8 ] 
19] 
[10] 
[11] 
[12] 
[13] 
[14] 
[15] 
[16] 
[17] 
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Note: Columns 25 through 72 are not shown. 

Figure 3.2. szSayi ng in FIXSTR.C . 
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I n Listing 3.9, RAGSTR.C showsa different way of allocating the strings. In this 
program, C has been told to allocate an array of string pointers, and then giveconstants 
asinitializers.Thistechniquewastesno space, and with two allocated arrays(oneisthe 
pointer to a string array, and theother isthestring array that's being pointed to), only 
521 bytes of storage are req u i red . 

L isting 3.9. RAGSTR.C. 

/* RAGSTR, written 20 May 1 9 9 2 by Peter D. Hipson */ 
/* Non-fixed-length strings in a program. */ 

# i n c I u d e <stdio.h> // Make includes first part of file 

# i n c I u d e <string.h> // For string functions. 

int main(void); // Define ma i n ( ) and the fact that this program doesn't 
/ / use any passed pa r a met er s . 

int ma i n ( ) 

{ 

int i ; 

char *szSayi ng[ ] = 
{ 

"Firestone's Law of Forecasting:", 

Chicken Little only has to be right once.", 

" Ma n I y' s Max i m: " , 

Logic is a s y s t e ma t i c me t h o d of coming to", 
the wrong conclusion with confidence.", 

" Moe r ' s truism:", 

The trouble with most jobs is the job holder's", 
resemblance to being one of a sled dog team. No one", 
gets a change of scenery except the lead dog.", 

continues 
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Listing 3.9. continued 



"Cannon's Co mme n t : " , 

If you tell the boss you were late for work because you", 
had a flat tire, the next morning you will have a flat tire." 

}; 

p r i n t f ( 

"Number of lines is %d\ n" 
"size of i t e m i s %d \ n " 
"size of (char) is %d \ n " , 

sizeof(szSaying) / sizeof(szSaying[0]), // Number of elements. 
sizeof(szSaying[0]), // Size of char * 

si zeof ( szSayi ng[ 0] [ 0] ) ) ; // Size of char 

s wi t c h ( s i z eof ( c ha r * ) ) 

{ 

case 2: / / Near pointers 

pri ntf( "Addr I e n s a y i n g \ n " ) ; 
break; 

case 4: // Far pointers, 8 0 8 x segmented pointers, 
pri ntf("Address I e n s a y i n g\ n " ) ; 
break; 

} 

for (i = 0; i < ( s i z eof ( s z Say i n g ) / s i z eof ( s z Sa y i n g [ 0 ] ) ) ; i + + ) 

{ 

pri n t f ( " %p %3d ' %s ' \ n" , 
szSayi n g [ i ] , 
st r I en( szSayi ng[ i ] ) , 
szSayi ng[ i ]) ; 



return ( 0) ; 



N oticethatthemain bodyof theprogram, especiallythet or ( ) loop used to print 
the strings, is identical in each program, despite the fact that each program has two 
different types of array addressing. 
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Figure3.3 shows an exampleof how the memory for RAGSTR.C'sszSayi ng is 
al I ocated an d u sed . I n th i s program , s z s a y i n g i s a si n gl e-d i men si on al array of ch aracter 
pointers. Each pointer then is initialized to point to thecorrect initializing character 
string. 



sz Sayings 
sz Sayings 
sz Sayings 
sz Sayings 
sz Sayings 
szSayings 
sz Sayings 
sz Sayings 
sz Sayings 
sz Sayings 
sz Sayings [ 
sz Sayings [ 
szSayings[ 
szSayings[ 
szSayings[ 
szSayings[ 
szSayings[ 
szSayings[ 
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the n 



Note: Columns after 24 are not shown. 

Each element in szSayings points to a string 
constant. 



Figure 3.3. szsayi ng in RAGSTR.C. 



Don't be concerned if this discussion leaves you confused— certain parts of the 
C language, and the way it is used, can confuse anyone. The important factors in the 
preceding two programs include thefollowing: 

1. A two-dimensional array of type char, accessed with only one subscript, 
effectively returns a pointer to a character string. 

2. A single-dimensional array of typec ha r * can be initialized with a set of string 
constants. 

3. If a single-dimensional array of typec ha r * is initialized with a set of string 
constants, you should be careful about modifying them. T he process of 
modifying a string constant is undefined under AN SI C, and many compilers 
keep only one copy of a set of identical strings (also legitimate under ANSI C ). 

4. A single-dimensional array of typec ha r *, initialized with a set of string 
constants, uses less memory than a two-dimensional array of type char. 
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5. A two-dimensional array of type char can be initialized and effectively modi- 
fied by a program. 

W hen you are working under the constraint that character strings stored in a 
ragged-right format aredifficult— if not impossible— to modify, thisformat can save 
a large amount of wasted storage space. 

Summary 

In this chapter, you learned about pointers and indirection. 

• Pointers are generally variables whose contents are the address of a memory 
object. 

• Indirection is the modification of the memory object pointed to by a pointer. 

• Strings are arrays of type char .Theend of a string is indicated by the null 
character. 

• Indirection is used often in functions that must modify one (or more) of the 
parameters th at was passed to th e f u n cti on . 

• Strings are best protected by good programming style: Be sure all buffers and 
string variables can hold the objects placed in them. 

• Strings can be stored in a ragged-right format that saves memory. G enerally, 
such strings are difficult to modify. 



98 




Special Pointers and 
Their Use 

Chapters 2 and 3 described pointers as they pertain to data objects. This chapter 
discusses pointers that point to objects other than data. J ust as you can have a pointer 
that points to a data object, you can also have a pointer that points to a function. 
Pointers have several special usesin programming, too.Onesuch useisto obtain the 
program's name and any parameters that have been entered by the user and passed to 
the program by the operating system. 

Command Line Arguments 

Command line arguments are vital to many programs you create. Command line 
arguments areused for options, input and output data sources, and toenabletheuser 
to pass parameters to the program. 
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The operating system processes the arguments the user enters, and places each 
onein astring that ispointed to by a pointer that you can access. Suppose that theuser 
enters the following command line: 

WONDER / Why Ask. dat 

Theprogram can accessnotonlytheprogram'sname, but also thecommand line 
arguments. T hese are passed to the ma i n ( ) function as parameters. U ntil now, the 
ma i n ( ) function has taken no parameters; in reality, however, three parameters are 
passed to ma i n( i when it is called. Thefunction prototype for the ma i n( ) function is 



Theargc parameter, an integer, contains the number of dementsin the passed 
array ofargvi ] . Becausethefirstmemberofargvi ] istheprogram'sname(usuallythis 
isafullyqualified name, completewith thedriveand directory information), thevalue 
of argc isalwaysat least 1. Some compilers and operating systems don't provide the 
program name, but haveargvi o] point instead to some predefined string constant, 
such as - r . 

The* a r g v [ ] parameter is an array of c h a r pointers. Thefirst element in ar gv [ ] 
always points to the program's name, and each subsequent member points to a 
parameter. Each parameter is separated by the operating system's default parameter 
separator, usually a blank or comma. U nder the PC 's D 0 S operating system, only a 
blank is used as a separator. T he end of this list of parameters can be determined by 
either using a r g c or testing the pointer, which isNuu to signify the end of the list. 

The* envp [ ] parameter is an array of char pointers. Thefirst element in ar gv[ ] 
points to the first environment string (when you are using D 0 S on the PC ). Each 
subsequent member points to a succeeding environment string. Each environment 
string looksjust likeit doeswhen you enter theD OS command SET, whereyou have 
an environment variable, an equal sign, and astring. T heend of this I ist of environment 
stringscan be determined by testing each envpi ] pointer, when null is encountered, 
signifying the end of the environment list. 

Listing 4.1 is a simple program that prints both the passed parameters and the 
environmentstringstothescreen.Thisprogram'soutputdependssomewhaton which 
operating system it runs; however, it shouldn't fail when it is run under different 
operating systems. 



i n t ma i n ( 



i nt 

char 

char 



argc, 

* a r g v [ ] , 

* e n v p [ ] 
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Listing 4.1. MAINARGS.C. 



/* MAI NARGS , written 22 May 1 9 9 2 by Peter D. Hipson */ 
/* This program prints a program' s arguments. */ 

# i n c I u d e <stdio.h> // Make includes first part of file 

tinclude <string.h> // For string functions. 

i nt ma i n ( // Define ma i n ( ) and the fact that this program uses 

i nt a r gc , / / the passed pa r a met er s . 



char * a r g v [ ] 

char * e n v p [ ] 
) ; 

n t ma i n ( 

i n t a r g c , 

char * a r g v [ ] 

char * e n v p [ ] 



{ 

i nt i ; 

p r i n t f ( " \ n " ) ; 

pri ntf("Program n a me is 1 %s 1 \ n \ n " , 
a r g v [ 0] ) ; 

// argc includes the program na me, so decrement for actual 
/ / passed pa r a met er s . 

printf("Nu mb e r of p a r a me t e r s %d \ n \ n " , 
argc - 1 ) ; 

// It's just as valid is to use: 
/ / for ( i =1; i < a r gc ; i ++) 

for (i = 1; a r gv [ i ] ; i+ + ) 

continues 
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Listing 4.1. continued 

{ 

pri ntf( "Passed p a r a me t e r %2 d is 1 %. 5 0 s 1 \ n " , 
i , 

ar gv[ i ] ) ; 

} 

pri n t f ( " \ n " ) ; 

// Environment variables may not be meaningful for all 
// operating systems. Check the compiler's documentation. 
// If this information is not available on your system, 
// delete the below f o r ( ) loop. 

for ( i =0; envpl i ] ; i ++) 

{ 

p r i n t f ( " E n v i r o n me n t string %2 d is 1 %. 5 0 s 1 \ n " , 
i , 

envpl i ]) ; 

} 

return ( 0) ; 

} 



As the M AINARGS program shows, the command line parameters are easy to 
access— the operating system does all the work for you. Almost all the work, at least. 
You still haveto process thearguments and do whatever is required of your program. 

Programs generally accepts three types of information: 

1. Input or output filenames 

2. 0 ptions, generally preceded by either a hyphen (-) or a slash (/) 

3. Parameters, which may or may not be in any given format 

Let's writea program that expectstwofilen am es(both input and output), several 
options, and a parameter. Thisprogram reformatsthelinesoftheinputtothenumber 
ofcharactersspecified bytheparameter. Possibleoptionsaretojustifythelinesormake 
them flush left or flush right. For simplicity, you don't write the program to actually 
do this work; however, you process the program's command line, and set flags, 
filenames, and thelinewidth. Listing 4.2, J U ST I FY.C , isthebasisfor thisprogram. 
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/* JUSTIFY, written 22 May 1 99 2 by Peter D. Hipson */ 

/* This program justifies text files (shell only). It assumes 

* and uses Microsoft's extensions to C. Readers with other 

* compilers may have to change the program to use the calls 

* that their compiler supplies to perform the same functions. */ 

/* This program assumes the command line syntax shown in 

* the GiveHelpU function. */ 

# i n c I u d e <stdio.h> // Make includes first part of file 
tinclude <string.h> // For string functions. 

# i n c I u d e <stdlib.h> // Standard include items, 
tinclude <process.h> // For exit() etc. 



#def 


ne 


LEFT 1 




#def 


n e 


RIGHT 2 




#def 


ne 


j USTI FY 3 




#def 


n e 


1 NNAME 1 




#def 


ne 


OUTNAME 2 




#def 


ne 


Wl DTH 3 




#def 


ne 


L AS T_ T H 1 NG 4 




#def 


ne 


ARG_ LEFT 


1 1 


#def 


n e 


ARG RI GHT 


r 1 


#def 


ne 


ARGJ USTI FY 1 


j ' 


#def 


ne 


ARG_ SLASH 


/ 1 


#def 


n e 


ARG_ DAS H 




#def 


ne 


ARG_ HELP 


? 1 


#def 


n e 


NOI NNAME 


1 


#def 


ne 


NOOUTNAME 


2 


#def 


ne 


BAD_ Wl DTH 


3 


#def 


n e 


BAD_ PARM 


4 


#def 


ne 


BAD_ OPT 1 ON 


5 


#def 


ne 


NAME Ml SSI NG 


6 



continues 



103 



Parti • HoningYour C Skills 



Listing 4.2. continued 



i nt main( // Define ma i n ( ) and the fact that this program uses 

i nt a r gc , / / the passed pa r a met er s . 



char * a r g v [ 
char * e n v p [ 



void Gi veHel p( 
i nt n Level , 
char * ps I t em) ; 



i n t ma i n ( 

i nt a r g c , 
char * a r g v [ ] , 
char *envp[ ] 
) 



{ 

char * ps z Te mp ; 

char s z Bu f f e r [ 1 2 9 ] ; // Temporary work buffer, 

char szProgram[ 30] ; 

char s z I n p u t F i I e [ 1 3 2 ] ; // Make large enough for your OS. 

char szOut put Fi I e[ 132] ; // Make large enough for your OS. 



/* strings for _splitpath() (which parses a filename) */ 
char szDr i ve[ _MAX_DRI VE] ; 
char szDi r [ _MAX_DI R] ; 
char s z F n a me [ _ MAX_ F NAME ] ; 
char szExt [ _ MAX_ EXT] ; 



nt i ; 

nt j ; 

nt n Cu r r e n t Pa r a met e r = I NNAME; 

nt nTempWi dt h =0; 

n t n L i n e Wi d t h =80; 

nt njustification = LEFT; 
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if ( a r g c <= 2) 

{ 

Gi veHel p( argc, NULL); 
r e t u r n ( 16) ; 

} 

_ s pi i t pa t h( a r gv[ 0 ] , 
s z D r i v e , 
s z Di r , 
s z F n a me , 
szExt ) ; 

strncpy(szProgram, szFname, sizeof(szProgram) - 1); 

for ( i = 1; a r g v [ i ] ; i+ + ) 

{ 

i f (argv[i ][ 0] == 1 / 1 | | ar gv[ i ] [ 0 ] =='■') 

{ /* You have an argument, convert to lowercase, and test. */ 
pszTemp = s t r I wr ( a r g v [ i ] ) ; 

for (j =1; j <strlen( pszTemp) ; j + + ) 

{ 

swi t ch( pszTemp! j ] ) 

{ 

case ARGLEFT: 

njustifi cation = LEFT; 
break; 

case A R G _ R I GHT: 

nj ust i f i cat i on = Rl GHT; 
break; 

case ARGJ USTI FY: 

nj usti f i cati on = J USTI FY; 
break; 

case ARG_ HE L P : 

Gi veHel p( NOI NNAME , NULL) ; 

exi t ( 4) ; 

break; 
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Listing 4.2. continued 

case ARG_ SLASH: 
case ARG_ DASH: 
break; 

def a u I t: 

Gi v e He I p( BADOPTI ON, &pszTemp[ j ] ) ; 
break; 

} 

} 

} 

else 

{ /* Either a filename or width. */ 
s wi t c h ( n Cu r r e n t Pa r a met e r ) 

{ 

case I NNAME: 

st r c py ( s z I n put F i I e, a r g v [ i ] ) ; 
nCur r ent Par amet er = OUT NAME ; 
break; 

case OUT NAME : 

st r c py ( s z Out put F i I e, a r g v [ i ] ) ; 
nCur r ent Par amet er = WI DTH; 
break; 

case WI DTH: 

ss c a nf ( a r g v [ i ] , " %d " , & n T e mp Wi d t h ) ; 

i f ( nTempWi dt h < 20 | | nTempWi dt h > 128) 

{ 

Gi veHel p( BADWI DTH, NULL); 

} 

else 

{ 

n L i n e Wi dt h = n T e mp Wi d t h ; 

} 

nCur r ent Par amet er = L AS T _ T H I NG; 
break; 
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def a u I t : 

Gi v e He I p( BAD_ PARM, NULL) 
break; 



if ( nCur rent Parameter < Wl DTH) 

{ / * Didn't get t wo f i I e n a me s ! * / 

Gi v e He I p( NAME_ Ml SSI NG, NULL) ; 

r e t u r n ( 16) ; 

} 



p r i n t f ( " \ n " ) ; 
p r i nt f ( 

" %s would read the file 1 %s 1 and write the file ' %s ' \ n \ n " , 
s z P r o g r a m, 
s z I n p ut F i I e, 
szOut put Fi I e) ; 

s wi t c h ( n J us t i f i c a t i o n ) 

{ 

case LEFT: 

pri ntf("The lines would be %d characters long, left \ 
a I i g n e d \ n " , 
n L i n e Wi d t h ) ; 
break; 

case Rl GHT: 

pri ntf("The lines would be %d characters long, right \ 
a I i g n e d \ n " , 
n L i n e Wi d t h ) ; 
break; 

case J USTI FY: 

printf("The lines would be %d characters long, justified\n 

n L i n e Wi d t h ) ; 
break; 

} 
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Listing 4.2. continued 

/* In the final version of this program, the files would 

* be opened next and the input file would be read into a buffer, 

* formatted according to the wishes of the user, and written 

* to the output file. At the end, the files would be closed, 

* and perhaps some statistical information could be 

* presented to the user. 
*/ 



return ( 0) ; 

} 



void Gi v e He I p( 



p r i n t f ( " \ n " ) ; 

s wi t c h ( n L e v e I ) 
{ 

case NOI NNAME: 

case NOOUTNAME: // Not enough parameters! 
pr i ntf ( 

" FORMAT [-r|-l|-j] inputfile outputfile width\n" 



\n" 

inputfile - is the input file n a me \ n " 
outputfile - is the output file name \ n " 
\n" 

width is the desired output width (20 to 128) \n" 
(default is 80 characters) . \ n" 
\n" 

Note: lines are concatenated, paragraph breaks a r e \ n " 
signaled with a blank I i n e \ n \ n " ) ; 



i nt 
char 



n Level , 
* ps I tern) 



where \ 
Options - 



n " 



r (or / r ) to right align \ n " 
I (or / I ) to left align \ n" 
j (or / j ) to j ust i fy\ n" 



break; 
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case BAD_WI DTH: 
p r i n t f ( 

"The width parameter must be between 20 and 128! \n" 
"the wi dt h is i g nor ed \ n " ) ; 
break; 

case BAD_ PARM: 

p r i n t f ( " Excessive parameters have been entered \ n") ; 

/ * Force a display of full help! */ 

Gi veHel p( NOI NNAME, NULL); 
break; 

case BAD_ OPT I ON: 

p r i n t f ( " 1 %c 1 is an invalid option! (Use only ■ I , ■ r or ■ j ) \ n " , 
* ps I t em) ; 

break; 

case NAME_ Ml SSI NG: 

printf("One or both of the required file names is mi s s i n g ! \ n " ) ; 

/ * Force a display of full help! */ 

Gi veHel p( NOI NNAME, NULL); 
break; 

default: 
p r i n t f ( 

"An unspecified error occurred! FORMAT has ended! \ n " 
) ; 

exi t ( 16) ; 
break; 

} 

} 
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This isn't so hard, isit?You have three possibleoptions in J U ST I FY. You don't 
check to see whether one of these options has been entered— you just accept the last 
one entered. You can set a flag, and if too many options are entered or there are 
conflicting options, warn the user. The syntax of JUSTIFY shows the following: 

1. The filenames (input and then output) and the width must be entered in that 
order. 

2. T he options must be preceded by either a slash (/) or a dash (-) option flag. 
One or more options can follow the option flag. 

3. The options can be entered anywhere in the command line, before, after, or 
interspersed with other parameters. 

4. Thefilenames must beentered; the width, however, isoptional. 

5. TheGi v e He i p( ) function is recursive— it calls itself to givethecommand 
syntax for some errors. 

You can useJUSTIFY as a shell to create almost any simple utility program by 
changing what it expects for files, parameters, and options 

So that you have a better understanding of what JUSTIFY does with the 
command linearguments, let'slook at several partsoftheprogramin detail. First, you 
check to see that there are at I east two command linearguments. Becauseboth an input 
and an output filenamearerequired, if there arenot two arguments, one(orboth) of 
theseismissing. Thistest isn't exhaustive— you musttest again later to makesurethat 
you h ave received two f i I en ames an d n ot j u st a I ot of opti on s. T h e test f or th e n u mber 
of arguments is simply: 

if ( argc <= 2) 

{ 

Gi v e He I p( argc, NULL); 
r e t u r n ( 1 6 ) ; 

} 

The return's value is passed back to the operating system, and if this program 
was run under DOS, the value can be tested using the DOS BATCH command i f 

errorl evel co mma n d . 

After you havechecked toseethatyou havetheminimum number of command 
linearguments, rather than hard-code the name of the program, you then extract the 
program 's n ame. Y ou do th i s extracti on so th at, i f th e u ser h as ren amed you r program , 
you present the user with the correct program name. It's confusing to rename a 
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command and have theerror messages continueto givetheold name. You then loop 
through the list of command line arguments, using a simplef o r ( ) loop: 

for ( i = 1 ; a r g v [ i ] ; i + + ) 

{ 

You test for theterminating null command lineargument pointer that signifies 
theend of the list. For each parameter, you look at the first character. If it is either a 
slash or a dash, the command lineargument is an option: 

if (argv[i][0] == 1 / 1 | | a r g v[ i ] [ 0] =='-') 

{ /* You have an argument, convert to lowercase, and test. */ 
pszTemp = s t r I wr ( a r g v [ i ] ) ; 

You convert options to lowercase (to minimize the testing) because you don't 
have case-sensitive options in this program. Because in some programs the options 
- p and- p have different meanings, it'sunlikely that users will remember thedifference 
between thetwo. M ake your program user-friendly by ignoring case if possible. 

After changing thecase, you simply loop through theoption's string. Start with 
the second character because you know that the first character is the slash or dash. 
U sing a switch, you check each valid letter option, and when there is a match, you set 
that option as required. Some programs have used theslash astheoption prefix flag, 
and a dash to turn the option off; however, I suggest that you turn an option on with 
one letter, and off with another. Two-letter options (common with compilers and 
other complex programs) can be processed by looking at thefirst letter, and then the 
second, simply by adding a second nested s wi t c m ) statement where needed: 

for ( j = 1; j < st r I en( pszTemp) ; j ++) 

{ 

swi t ch( pszTemp! j ] ) 

{ 

case ARG_ LEFT: 

njustification = LEFT; 
break; 

case ARG_ Rl GHT: 

nj ust i f i cat i on = Rl GHT; 
break; 

case ARGJ USTI FY: 

nj ust i f i cat i on = J USTI FY; 
break; 
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case ARG_HELP: 

Gi v e He I p( NOI NNAME , NULL) ; 

exi t ( 4) ; 

break; 

case ARG_SLASH: 
case ARG_ DAS H: 
break; 

default: 

Gi v e He I p( BADOPTI ON, &ps z Te mp [ j ] ) ; 
break; 

} 

} 

} 

Intheprecedingswi tcho block, you ignore imbedded si ashes and dashes. Users 
commonly enter a set of options with a slash or dash before each option and with no 
intervening spaces. 

You also process correctly the/ ? option, the relatively standard syntax for help. 
You can also process / h for help. 

N oticethedef aui t : in thisblock: Iftheuserhasentered an unrecognized option 
letter, you providea message that indicates theinvalid option letter. 

I nthefollowing block, you haveeitheroneofthefilenamesorthewidth specifier. 

el se 

{ /* Either a filename or width. */ 

These three items are positional; that is, the input filename is always thefirst of 
thethree, theoutputfilenameisthesecond, and thewidth (which isoptional) isalways 
thethird.Therearenumerousreasonsforthisorder: Onereason isthatafilenamecan 
bea number (and therefore, width cannot befirst if it isto beoptional); another reason 
is that the two filenames must be provided in a known order because they are 
indistinguishable to the program. 

You keep track of which of these three items you are processing by using the 
variable ncur r en t par a met er . This variable works as a state machine (see the "State 
M achines" section, later in thischapter), and changes its state every timea parameter 
is encountered: 
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s wi t c h ( n Cu r r e n t Pa r a met e r ) 
{ 

case I N N A ME : 

s t r c py ( s z I nputFi I e, a r g v [ i ] ) ; 
nCur r ent Par amet er = OUT NAME ; 
break; 

case OUT NAME : 

s t r c py ( s z Out put F i I e, ar gv[ i ] ) ; 
n Cu r r e n t Pa r a met e r = Wl DTH; 
break; 

case Wl DTH: 

s s ca nf ( a r g v [ i ] , "%d", &nTempWi dt h) ; 

i f ( nTempWi dt h < 20 | | nTempWi dt h > 128) 

{ 

Gi veHel p( BADWI DTH, NULL); 

} 

el se 

{ 

n L i n e Wi d t h = nTe mp Wi d t h ; 

} 

nCur r ent Par amet er = L AS T_ T H I NG; 

break; 

default: 

Gi veHel p( BAD PARM, NULL); 
break; 

} 

} 

} 

Thewidth parameter istested, and thevariablen Li newi dth isupdatedonlyifthe 
width is within theprogram's bounds of 20 to 128. (I'm not saying that these bounds 
are realistic— just that they can be.) You know that the user entered at least two 
parameters, but you don't know whether two of them werefilenames. A confused user 
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might have entered thecommand name, with no filenames, and with all three option 
letters as separate command line parameters: 

j U S T I FY I] H -r 

This command line syntax has the minimum number of command line 
parameters; however, you don't haveanyfilen am es. You test for thiswith thefollowing 
code: 

if ( nCur r ent Par a met er < Wl DTH) 

{ / * Didn't get two f i I e n a me s ! * / 

Gi v e He I p( NAME_ Ml SSI NG, NULL) ; 

r et ur n( 16) ; 

} 

Again, thestatemachinevariable, ncurrentparameter, letsyou know how many 
filenamestheuser entered. If thestatemachinevariableisn't at least to thewi dth state, 
you didn't get the required filenames. 

The remainder of the program is simple because I didn't write the text- 
formatting part of this program. It has minimal error checking and a simple error- 
messagefunction that receivesan error messagecodeand an optional character pointer. 
T hecharacter pointer can point to either a single character or a string. You must make 
sure that the message's pr i ntf ( ) statements know what the pointer is pointing to. 

One of the interesting things about the error message processor is that it is 
recursive: It calls itself when the user needs to have the full command syntax. The 
following syntax is accepted: / 1 r . That is, more than oneoption can follow the si ash 
or dash option flag. If the user has entered a number of optionsfollowing theslash or 
dash, and one of the options is invalid, do you stop processing this command line 
parameter? Probably not, but you must consider all possible situations and program 
accordingly. 

Function Pointers 

F unction pointerscan beused to do almost anythingyou can do with afunction name. 
You can still pass parameters to afunction that is being called with a pointer. 

Sometimes, using pointersto functionsistheonly way to do something. A classic 
example is the library function qsort ( ) , which takes a pointer to a function. This 
pointer often iscoded as a constant; you might, however, wantto codeitasafunction 
pointer variable that gets assigned the correct function to do qsor t ( i 's compare. 



114 



Special Pointers and Their Use 



Theprogram FU N PTR.C, in Listing 4.3, has an exampleof one use of function 
pointers. This program calls a different function for each character in an input string. 
Although initializing thearray of function pointers may take some time (and effort) 
in most programs, thistimefactor isnot as significant astheeffort to program separate 
calls, even if the separate calls are in a function by themselves. 




L isting 4. 3. FUNPTR.C. 



/* FUNPTR, written 22 May 1 9 9 2 by Peter D. Hipson */ 
/* An array of function pointers. */ 

# i n c I u d e < s t d i o . h > // Make includes first part of file 
tinclude <string.h> // For string functions. 

tinclude <stdlib.h> // Standard include items. 

# i n c I u d e <process.h> // For e x i t ( ) etc. 

i nt main( // Define ma i n ( ) and the fact that this program uses 

i nt a r gc , / / the passed pa r a met er s . 
char * a r g v [ ] , 
char * e n v p [ ] 



void NonPri nt(const char chChar) 

void Letter( const char chChar); 

void Number(const char chChar); 

voi d Space( const char chChar ) ; 



n t ma i n ( 

i n t a r g c , 

char * a r g v [ 

char *envp[ 



{ 

void ( *f unct i on[ 2 5 6] ) ( const char ) ; 
char * ps z Temp ; 

char szBuf f er [ 512] ; // Your input buffer. 

continues 
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Listing 4.3. continued 

i nt i ; 

/* First initialize your array of function pointers. Notice that, 

* because you have specified what the function pointed to by this 

* pointer requires for a parameter, all the functions assigned to 

* this array require the same number and types of parameters. 

* The parameters could have been omitted, but then you don't 

* benefit from type checking on parameters. */ 

for ( i =0; i < 2 5 6; i ++) 

{ 

if ((unsigned char ) i < 1 1 ) 

{ 

f u n c t i o n [ i ] = No n P r i n t ; 

} 

else 

{ 

if ((unsigned char ) i >= 1 0' && 
(unsigned c ha r ) i <= 1 9' ) 

{ 

f u n c t i o n [ i ] = N u mbe r ; 

} 

else 

{ 

if ((unsigned c har ) i == 1 1 ) 

{ 

f unct i on[ i ] = Space; 

} 

else 

{ 

f unc t i on [ i ] = Letter; 

} 

} 

} 

} 

whi I e ( g et s ( s z Buf f e r ) ) 

{ 

for ( i =0; sz Buf f er [ i ] ; i + + ) 
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{ 

/* Now, this is nice syntax: */ 

functi on[ ( i nt)szBuffer[ i ] ] ( s z Buf f e r [ i ] ) ; 

} 

} 

r e t u r n ( 0 ) ; 

} 

void N o n P r i n t ( 

const char chChar) 

{ 

/* Make it printable by adding a 1 @' to it.*/ 
pr i ntf ( " CTRL ■ 1 %c 1 \ n " , c hChar + 1 @' ) ; 

} 



void Space( 

const char chChar ) 

{ 

pri ntf( "Space 1 %c 1 \ n " , chChar); 

} 

void Letter! 

const char chChar ) 

{ 

pri ntf( "Letter 1 %c 1 \ n " , chChar); 

} 



void N u mb e r ( 

const char chChar ) 

{ 

printf("Nu mb e r 1 %c 1 \ n " , chChar); 

} 
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(Remember, I didn't promise that FU N PTR does anything significant.) 

I'veshownthatfunctionprototypesareimportant.but, inaprogramthatisusing 
function pointers, they arevital. N oticethateach of thefunctionsthatwill beassigned 
tothefunction pointer hasidentical prototypes— their return types arethesameand 
their parameters match equally. 

L et's I ook at some of th e f u n parts ofFUNPTR.Thedecl arati on of th e array of 
function pointers has a number of critical parts: 

void ( *funct i on[ 256] ) ( const char); 

The void tells C that these functions don't return anything. If the functions 
return a value, use that value's type. Because the order and positioning of the 
parentheses are critical, the name of the function pointer is next. If this were not an 
array declaration, the declaration would be 

void ( * f u n c t i o n ) ( c o n s t char); 

Following thefunction pointer name are the function's parameters (again, the 
parentheses are important). Keep it simple— try to avoid having functions assigned 
that take different types or counts of parameters. H aving functions with different 
parameters weakens the compiler's capability to check for errors, although it is 
possible. 

After declaring thefunction pointer array, you initialize it. When you assign a 
function's address to a function pointer, do not use the function's parentheses 

for ( i =0; i < 2 5 6; i + + ) 

{ 

if ((unsigned char) i < 1 1 ) 
{ 

fundi on[i] = No n Print; /* NOTICE: No (), just the name */ 

} 

else 

{ 

if ((unsigned char ) i >= 1 0' && 
(unsigned char ) i <= 1 9' ) 

{ 

f u n c t i o n [ i ] = Number; /* NOTICE: No (), just the name */ 

} 

else 
{ 

if ((unsigned c ha r ) i == 1 1 ) 
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{ 

fundi on[i] = Space; /* NOTICE: No (), just the name */ 

} 

else 

{ 

fundi o n [ i ] = Letter; /* NOTICE: No (), just the name */ 

} 

} 

} 

} 

BecauseFU N PTR has an array of 256 possible functions to call, you initialize 
all of them. Becauseyou potentially call adifferentfunction for each of thepossible256 
characters in thecharacter set and because(with afew exceptions) theuser can enter 
any character, you must make sure that all the members of thefunction pointer array 
are initialized. 

After you have initialized thefunction pointer array, you can continue with the 
rest of the program. Use a simple loop to get a linefrom the keyboard, and then for 
each character in the line, call the appropriate function: 

wh i I e ( gets( szBuffer) ) 

{ 

for ( i =0; s z Buf f e r [ i ] ; i + + ) 
{ 

/* Now, thisisnicesyntax: */ 

f unc t i on [ ( i nt ) sz Buf f er [ i ] ] ( s z B uf f e r [ i ] ) ; 

} 

} 

Noticethestrangecall fundi on[ in (using an array of function pointersdoesn't 
always look good). 1 1 diminatesa largei f ( ) ...ei se block that savesvaluableprogram- 
mingtimeifthisl etter-by- 1 etter parsing of thestring isdone often ( m ore th an on ce) 
in a program. A second important factor isthat the wh i i e( ) loop runsfaster because 
manyifo statements are eliminated. 

U sing a function pointer as a parameter in a function call is not unusual. As 
mentioned, the library function qsort ( ) does this. 

Look at the following prototype for qs o r t ( ) .The prototype is in the standard 
header file stdlib.h and in search. h, if your compiler has such a header file. 
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voi d _FAR_ _ _ c d e c I q s o r t ( 

void _FAR_ *, /* array to be sorted */ 

size_t, /* number of elements in the array */ 

size_t, /* size of each array element */ 

i nt (_ FAR _ __ cdecl *)(const void _ FAR_ *, const void _ F AR_ *)); 

qs o r t ( ) 's first three parameters are as expected: an array pointer, two integers 
showing the number of elements in the array, and the size of the elements. 

Thefinal parameter in thecalltoqsorti ) is the most interesting one. 1 1 specifies 
th at th e parameter i s the add ress of a f u n cti on th at retu rn s an i n t val ue an d takes two 
far pointers. Both ofthesepointersaredeclaredastypevoi d so that any typeof pointer 
can bepassed;thefunction being called, however, must know thepoi nter'stype. Because 
each call to qsort { ) is generally for a specific type of array, the function being called 
will know about the array's types, qsort ( ) isdiscussed in detail in Chapter 10, "Data 
M anagement: Sorts, Lists, and Indexes." 

Menus and Pointers 

Peter'sprogrammingrulenumber6: Don't reinventthewhed.O KJt'snotan original 
rule, but even with Peter's rules, I didn't want to reinvent the rule. 

T here are several easy waysto put menus in a program without writing them all 
yourself. The first and by far the best is to use Windows. N o kidding, Windows is an 
effective way to create slick user interfaces. D on't be put off by the learning curve of 
Window's programming— it is much less than writing the user interface yourself. 

If you are determined not to use Windows, systems are available that enable 
almost any type of program to haveextensivemenu support, such aspull-down menus, 
pop-up dialog menus, and so on. 

It'swdl beyond thescopeof thisbookto writean entirepull-down menu system. 
Onesimpletext-only system requiresmanythousandsof linesof code. This book can, 
however, cover many of the basics. 

A pull-down menu might, for example, call a different function for each of the 
menu items. Thefunction call tothemenu system might includesuch parameters as 
an array for each menu item's text and an array of function pointers to call for each 
menu item. 
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You can look at the top bar menu separately and use a rather simple call to a 
function such asgetchi ) toprocessthekeystrokesentered. Part of M EN U l.C assumes 
that the program is running under DOS on a PC, that the AN SI .SYS device driver 
(used for screen control) is installed, and thatthecompiler supports thefunctionsthis 
program calls. 

In Listing 4.4, the program M EN U l.C implements a simple pull-down menu 
that has a simple dialog box to enable the user to enter a filename. 



Listing 4.4.M E NU l.C. 

/* MENUl, written 23 May 1 9 9 2 by Peter D. Hipson */ 
/ * A s i mp I e men u program. * / 



/* This program assumes and uses Microsoft's extensions to C. 

* Readers with other compilers may have to change the program 

* to use the calls that their compiler supplies to perform 

* the s a me functions. * / 



#i nc I ude <st di o. h> 

# i n c I u d e <s t r i n g . h > 

#i nc I ude <st dl i b. h> 

#i nc I ude <pr oces s . h> 

# i n c I ude <c o n i o . h > 

#i nc I ude <ct ype. h> 



Make includes first part of file 
For string functions. 
Standard include items. 
For exi t ( ) , etc. 

For get ch( ) and other console I/O. 
For char functions ( _t oupper ( ) . . . ) 



/* ANSI . SYS screen control #define's below: 

*/ 



#def 


ne 


BOLD 


" \ x 1 B [ 1 m" 


#def 


ne 


NORMAL 


" \ x 1 B [ 0 m" 


#def 


n e 


RED 


11 \ x 1 B [ 3 1 m 


#def 


ne 


BLACK 


" \ x 1 B [ 3 0 m 


#def 


ne 


GREEN 


11 \ x 1 B [ 3 2 m 



#def i ne CLEARJCREEN " \ x 1 B [ 2 J " 
#def i ne CLEAR EOL "\ xlB[ K" 

tdefine MOVE_ CURSOR " \ x 1 B[ %d ; %df " 

continues 
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Listing 4.4.continued 



char szTopBarN = {/* Must be 80 characters long MAX. */ 



C L E A R_ 


SCREEN 




BOLD" F 


1 NORMAL 


i 1 es 


BOLD" E 


1 NORMAL 


di t 


BOLD" V 


1 NORMAL 


i ew 


BOLD" P 


1 NORMAL 


r oj ec t 


BOLD" R 


1 NORMAL 


u n 


BOLD" D 


1 NORMAL 


ebug 


CLEAR 


EOL 





}; 

/* Line-drawing characters for the PC = " I H -i L - 1 - t r - + rH"*/ 

void Me n u B a r ( ) ; /* Never called! Make the array look good. */ 

char *szFi I es[ ] = { 
i ' 

" " BOLD" N" NORMAL" ew 

11 " BOLD" O" NORMAL" pen 

11 " BOL D" C" NORMAL 11 1 ose 

" " BOL D" S " NORMAL " a v e 

" save "BOL D" A" NORMAL 11 s 

■ 1" , 

" " BOLD" P" NORMAL" r i nt |" , 

■ 1 ■ , 

11 e" BOLD" X" NORMAL" i t |" , 

„ I. 

NULL }; 



vo 


d 


Do F i 


es New( ) ; 


vo 


d 


Do F i 


esOpen( ) ; 


vo 


d 


Do F i 


esCI os e( ) ; 


vo 


d 


Do F i 


esSave( ) ; 


vo 


d 


Do F i 


esSaveAs( ) 


vo 


d 


Do F i 


es Pr i nt ( ) ; 


vo 


d 


Do F i 


esEXi t ( ) ; 
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void (*Fi I esFuncti ons[ ] ) (voi d) 
MenuBar , 
Do F i I es New, 
Do F i I es Open , 
Do F i I esCI ose, 
DoFi I esSave, 
DoFi I esSaveAs, 
MenuBar , 
Do F i I es P r i nt , 
MenuBar , 
DoFi I esEXi t , 
MenuBar , 
NULL 

}; 



i nt ma i n ( // Define ma i n ( ) and the fact that this program uses 

i nt a r gc , / / the passed pa r a met er s . 

char * a r g v [ ] , 

char * e n v p [ ] 
) ; 

void P u I I Do wn ( c h a r **, int, void ( c d e c I * * ) (voi d ) ) ; 

i n t ma i n ( 

int a r g c , 

char * a r g v [ ] , 

char *envp[ ] 



{ 

char chEntered; 

while ( 1 ) 

{ 

pr i n t f ( s zTop Ba r ) ; 

chEntered = ( c h a r ) g e t c h ( ) ; contjnues 
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Listing 4.4. continued 



if (chEntered == '\0' || chEntered == ' \ x E 0 ' ) 
{ // PC Extended character (function key etc.) 
chEntered = ( char) getch( ) ; 

} 

pri n t f ( MOV E_ CURSOR, 10, 10); /* Using printfO fully here! */ 

s wi t c h ( _t o u pper ( ( i n t ) c h E n t er ed ) ) 

{ 

case 1 F 1 : 

P u I I Do wn ( s z F i I es , 1, F i I es F u n c t i o n s ) ; 
break; 

case 1 E 1 : 

pr i ntf ( 11 Edi t submenu called" CL E A R_ EOL ) ; 
break; 

case 1 V : 

pr i ntf ( 11 Vi ew submenu called" CL E A R_ EOL ) ; 
break; 

case 1 P 1 : 

pri n t f ( " Project submenu called" CLEAREOL) ; 
break; 

case 1 R 1 : 

printf("Run submenu called" CLEAREOL) ; 
break; 

case 1 D 1 : 

pr i ntf (" Debug submenu called" CLEAR_EOL); 
break; 

default: 

pr i ntf ( " I n v a I i d key! " C L EAR_ EOL ) ; 
break; 

} 
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r e t u r n ( 0 ) ; 

} 

void Pull Down( 

char * s z Me n u [ ] , 
i nt nCol umn, 

void ( __cdec I * p F u n c t i ons[ ] ) ( voi d) ) 



i nt i ; 

i n t n Me n u I t e m = ■ 1 ; 
char chEntered; 

for ( i = 0; s z Me n u [ i ] ; i ++) 

{ 

pri ntf ( MOVE_ CURSOR, i + 1, nCol umn) ; 
p r i n t f ( s z Men u [ i ] ) ; 

} 

while ( n Men u I t em < 0 ) 

{ 

chEntered = (char)getch(); 

if (chEntered == '\0' || chEntered == ' \ x E 0 ' ) 
{ // PC Extended character (function key etc.) 
chEntered = (char)getch(l; 

} 

chEntered = ( c h a r ) _ t o u p pe r ( ( i n t ) c h E n t e r ed ) ; 

/* find the correct menu item index */ 

if ( i sal num( ( i nt)chEntered) ) 
{ 

for ( i =0; s z Me nu [ i ] ; i + + ) 

{ 
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Listing 4.4. continued 

if ( s t r c h r ( s z Me n u [ i ] , chEntered)) 

{ 

n Me n u I tern = i ; 
break; 

} 

} 

} 

if ( n Me n u I tern >= 0 ) 

{ 

pFuncti ons[ nMenul tern] ( ) ; 

} 

} 

} 

void DoFi I esNew( ) 

{ 

pri ntf (MOVE_CURSOR, 20, 10); 
p r i n t f ( " F i I es , new 11 ); 
pri ntf ( MOVE_ CURSOR, 24, 10); 
pri ntf("Any key to continue 11 ); 
( v o i d ) g e t c h ( ) ; 

} 

void DoFi I esOpen( ) 

{ 

/* Presents to the user a simple get a filename dialog box, 

* enabling character string to be entered. Basic editing supported. 

*/ 

i nt i ; 

/* These hard-coded constants, for place me nt of dialog box, 

* nor mal I y woul d be passed. 
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*/ 

nt 



n Co I u mn = 15; 
n Ro w = 15; 
nl nputCol umn = 2; 
nl nputRow = 4 ; 



nt 



nt 



nt 



char szFi I eName[ 132] ; 
char *szFi I e s Op e n [ ] = { 



Enter the name of the file to open: 



NULL}; 

for ( i =0; szFi I esOpenl i ] ; i ++) 

{ 

pr i nt f ( MOVE_ CURSOR, i + nRow, nColumn); 
pr i n t f ( s z F i I es Open [ i ] ) ; 

} 

pr i ntf ( MOVE_CURSOR, 
nl nputRow + nRow, 
nl nputCol umn + n Co I u mn ) ; 

s c a n f ( " %s " , s z F i I e N a me ) ; 

p r i nt f ( MOVE_ CURSOR, 24, 10); 

p r i n t f ( " NAME : 1 %s 1 Any key to continue", szFileName); 
(void)getch(); 

} 

void DoFi I esCI ose( ) 



p r i nt f ( MOVE_ CURSOR, 20, 10); 



pri ntf( " Fi I es, close selected"); 



continues 
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Listing 4.4. continued 

pri ntf ( MOVE_ CURSOR, 24, 10); 
pri ntf("Any key to continue 11 ); 
( v o i d ) g e t c h ( ) ; 

} 

void DoFi I e s S a v e ( ) 
{ 

pri ntf ( MOVE_CURSOR, 20, 10); 
pri ntf("Fi I es, save selected 11 ); 
pri ntf ( MOVE_CURSOR, 24, 10); 
pri ntf("Any key to continue 11 ); 
( vo i d ) get c h ( ) ; 

} 

void DoFi I esSaveAs( ) 

{ 

pri n t f ( MOVE_ CURSOR, 20, 10); 

pri ntf("Fi I es, save as selected 11 ); 

pri ntf ( MOVE_ CURSOR, 24, 10); 

pri ntf("Any key to continue 11 ); 

( vo i d ) get c h ( ) ; 

} 

void DoFi I esPri nt( ) 

{ 

pri ntf (MOVE_CURSOR, 20, 10); 
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printf{" Files, print selected"); 
p r i nt f ( MOVE_ CURSOR, 24, 10); 
printf(" Any key to continue"); 
( v o i d ) g e t c h ( ) ; 

} 

voi d Do F i I esEXi t ( ) 

{ 

p r i nt f ( MOVE_ CURSOR, 20, 10); 
p r i n t f ( " F i I e s , exit selected"); 
exi t ( 0) ; 

} 

void Me n u Ba r ( ) 
{ 

/* This function is never called! */ 



M EN U l.C is the most complex program this book has discussed. It shows 
several important features, including passing an array of function pointers and using 
screen control and— of course— menus. 

0 neof thefirstthingsyou do in M EN U lisdefinesomestring identifiers. These 
identifiers are used to format the menu items, position the cursor, and perform other 
screen -management functions: 

/* ANSI . SYS screen control #define's below: */ 



#def i ne BOLD "\ xlB[ 1 m" 

#def i ne NORMAL "\ xlB[ 0m" 

#def i ne RED "\ xlB[ 31m" 

#def i ne BLACK " \ x 1 B [ 30m" 
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#def i ne GREEN 11 \ x 1 B [ 32m" 

#def i ne CLEAR SCREEN " \ x 1 B [ 2 J " 
#def i ne CLEAR EOL 11 \ x 1 B [ K" 

#d e f i n e MOVE_CURSOR " \ x 1 B [ %d ; %d f " 

Notice the identifier move cursor. Used with pri ntf ( ) and a set of integer 
parameters specifying cursor row and column, you can position thecursor using the 
following statement: 

pri ntf ( MOVE_ CURSOR, 10, 20); 

Thedefinition oftheprogram'stopmenu bar makes heavy useof string constant 
concatenation and AN SI screen control. 

char szTopBarN = {/* Must be 80 characters long MAX. */ 



C L E A R_ 


SCREEN 




BOLD" F 


1 NORMAL 


i 1 es 


BOLD" E 


1 NORMAL 


di t 


BOL D" V 


1 NORMAL 


i ew 


BOLD" P 


1 NORMAL 


r o j ec t 


BOLD" R 


1 NORMAL 


u n 


BOLD" D 


1 NORMAL 


ebug 


CLEAR 


EOL 





}; 

The maximum true length of thescreen's title bar is equal to thescreen's width. 
Counting these characters can be difficult; if you remove the ANSI screen-control 
identifiers and the string concatenation quotes, however, you can seethelength of the 
menu bar more easily. 

After thetop menu-bar string definition, you definefortheFi i es menu a pull- 
down that offers a number of common operations: 

char *szFi I es[ ] = { 



" BOL D" N" NORMAL" ew 
" BOL D" 0" NORMAL " pen 
" BOLD" C" NORMAL" I ose 
" BOL D" S 11 NORMAL " a v e 
save " BOLD" A" NORMAL" s 



130 



Special Pointers and Their Use 



" |" BOLD" P" NORMAL " r i nt 

ii ii 

" | e " B 0 L D " X " N 0 R MA L " i t 

II . ii 

NULL}; 

After you know what theFi i es pull-down menu will contain, you then buildthe 
function pointer array. You first define the functions, and then the array, and then 
initialize it with the functions that perform each task. 



void 


Do F i 


1 es New( ) ; 


void 


Do F i 


1 es Open ( ) ; 


void 


Do F i 


1 es CI os e( ) ; 


void 


Do F i 


1 es Sa ve ( ) ; 


void 


Do F i 


1 es SaveAs ( ) 


void 


Do F i 


1 es Pr i nt ( ) ; 


void 


Do F i 


1 esEXi t ( ) ; 


void 


(*Fi 1 


esFunct i ons 



[ ] ) ( vol d) = { 



MenuBar , 
Do F i I es New, 
Do F i I es Open , 
Do F i I esCI ose, 
Do F i I esSave, 
DoFi I esSaveAs, 
MenuBar , 
DoFi I esPri nt, 
MenuBar , 
DoFi I esEXi t , 
MenuBar , 
NULL 

}; 

N otice that you have allowed the number of initializers to define how many 
dementsarefoundinthisarray,andthatyou havesetthefinal member to null so that 
you can test for the end of the array if necessary. Setting the last element of an array 
of pointersto null isagood ideabecauseyou don't have to pass thelength of the array 
to functions that use it. 

Finally, just before you start themai n( ) function, you definethefunction that 
controls the pull-down menus. T his function's prototype is 

void P u I I Do wn ( c h a r **, int, void ( c d e c I **)(void)); 
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Notice how an array of pointers (usually written as * a r r a y [ ] ) is described as an 
array of pointers to pointers (type * * ). T hi sdescri pti on is necessary because you don 't 
specify the name of the actual array in this prototype. The array of function pointers 
must be specified with both the return values and parameters. In this program, both 
are simply voi <j. 

T h e mai n program hasj u st a I arge I oop th at reads th e keyboard an d processes th e 
characters. This program uses get cm ) to get a character (without echoing it to the 
screen); because this program runs on a PC, you test (and process) special keypresses, 
suchasthefunction keys. Other computers with different keyboardsmayrequiresome 
other changes to this part of the program. 

whi I e (1) 

{ 

pr i ntf ( szTopBar ) ; 
chEntered = (char)getch(l; 

i f ( chEntered == 1 \0' | | chEntered == 1 \ x E 0 ' ) 
{ // PC Extended character (function key etc.) 
chEntered = (char)getch(); 

} 

After a character is read in, it is converted touppercase(sothatitcan be tested), 
and then you useacase statement to find which ofthetop bar menu itemshasbeen 
selected. 

s wi t c h ( _t ou pper ( ( i n t ) c h Ent er ed ) ) 

{ 

case 1 F 1 : 

P u I I Do wn ( s z F i I es , 1, Fi I esFunct i ons) ; 
break; 

case 1 E 1 : 

pr i ntf ( " Edi t submenu called" CLEAREOL) ; 
break; 

case 1 V : 

printf(" View submenu called" CLEAR_E0L); 
break; 
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case 1 P 1 : 

printf(" Project submenu called" CLEAREOL) ; 
break; 

case 1 R 1 : 

printf("Run submenu called" CLEAR_EOL); 
break; 

case 1 D 1 : 

pri ntf("Debug submenu called" CLEAR_EOL); 
break; 

d ef a u I t : 

pr i ntf ( " I n v a I i d key! " C L EAR_ EOL ) ; 
break; 

} 

When atop bar menu item is selected (Files in this example), the p u i i Downi ) 
function is called. This generic function is provided with the starting column for the 
pull-down menu (the starting row is always 2), an array of char pointers pointing to 
each menu item, and an array of function pointers pointing to thefunctionsthat will 
becalled when a specific menu item iscalled. Except for f i i es, noneofthetopmenu 
items are implemented. 

puii Downo hasthecodetodisplaythepull-down menu. A better program would 
save the screen at the location where the pull-down menu is displayed and restore it 
when thefunction returns; thissimpleprogram, however, doesn't "clean up" after itself 
well: 

for ( i =0; szMenul i ] ; i + + ) 

{ 

pr i ntf ( MOVE_CURSOR, i + 2, nCol u mn ) ; 
p r i nt f ( s z Me n u [ i ] ) ; 

} 

Themenu items are printed, onetoaline, until theend of the list (signified by 
theNun pointer) isencountered. After thepull-down menu isdisplayed, you read the 
keyboard until avalid key is pressed, and then perform therequested action. Because 
this is a simple program, you again require the user to select a menu item before you 
let the user return to the main menu. 
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while ( n Me n u I tern < 0 ) 

{ 

chEntered = (char)getch(); 

if (chEntered == '\0' || chEntered == ' \ x E 0 ' ) 
{ // PC Extended character (function key etc.) 
chEntered = (char)getch(); 

} 

chEntered = ( c h a r ) _ t o u p pe r ( ( i n t ) c h E n t e r ed ) ; 
/* find the correct menu item index */ 

if (isalnum((int)chEntered)) 

{ 

for ( i =0; s z Me n u [ i ] ; i ++) 

{ 

if ( s t r c h r ( s z Me n u [ i ] , chEntered)) 

{ 

n Me n u I t e m = i ; 
break; 

} 

} 

} 

T o check the keys pressed by the user, you get the character pressed, convert it 
to uppercase, and then scan each menu item for the key character. Because each menu 
item is allowed only one capitalized character (thedesired character for thisaction), 
you can uses t r c hr ( ) to look at each of themenu lines. If no match isfound, you wait 
for the user to press a new key; if a match isfound, you call the appropriate function: 

if ( n Men u I t e m >= 0 ) 

{ 

p F u n c t i o n s [ n Me n u I t em] ( ) ; 

} 

} 

C al I i n g the correct f u n cti on i s as easy as i n dexi ng th e array of f u n cti on poi n ters. 

M EN U 1 isarelativelycrudeprogram, yetitexceeds300 linesof sourcecodeand 
doesn't do anything. Remember my comments about reinventing the wheel at the 
beginning of thechapter?N owyou can see why. I could writethisprogram (and make 
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it work properly) under Windows in less time than it took to write the entire thing 
myself. I had to write it, though, to provide the example of both menus and the use 
of arrays of pointers. N ow you can decide what you want to do. 

State Machines 

You might think that state machines are part ofyourstategovernment, but not for the 
purposes of this book. The example program JUSTIFY is a state machine (refer to 
Listing 4.1). M ost state machines consist of a controlling variable (the state variable), 
whose valueindicatesthecurrent operating status of the function (or program). The 
state variable generally is an integer value, and depending on its current state, can be 
changed to another state. 

Generally, in most state machines the state of the control li ng variable does not 
need to be incremented (or decremented) in singlesteps. For example, it may change 
directly from onestateto another. States general I yean be considered to beuniquebut 
equal. When you arewritingastatemachine,you must consider theprocess and what 
needsto bedone(seeFigure4.1). 




F i gu re 4 . 1 . A n exam p I e of a state m ach i n e's state tran si ti on s. 
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F i gu re 4 . 1 sh ows th at th e program h as a n u m ber of "states. "The state mach i n e 
part of JUST I FY is the processing of the three parameters: the input filename, the 
output filename, and the output width you want. 

Listing 4.5 shows the way the state machine works. The major part of this 
machineisa simples wi tch( ) loop, with acase tohandleeachstateAttheendofeach 
state's case statement is the code necessary to update the status of the state variable, 
ncur rent Parameter . The next timetheswi t ch( i statement is executed, this new state 
of n cur rent Parameter controls which case: statement is executed. As usual with a 
swi t ch( i statement, onlyonecase statement block is executed (you don't allow case 
statements to fall through, into thefollowing case statement, in this state machine). 

One important factor limits JUST I FY's state machine: You allow the state 
variableto change to only thenext state, and you don't allow states to beskipped. T he 
onlywaytogettothewi dth state, therefore, isfromtheouTNAME state, and theonly way 
to get to the outname state is from the i nname state. After the wi dth state has been 
achieved, any further changes in the state are errors because you have nothing else to 
get. T heresult isthat thenext statefrom thewi dth state is the error state, last thi ng, 
which, if processed, gives the user an error message. Listing 4.5 is the parameter 
processor from thej U ST I FY program. 

Listing 4.5. State machine from J USTIFY.C. 

swi tch( nCurrentParameter) 

{ 

case I NNAME: 

strcpy(szlnputFile, a r g v [ i ] ) ; 
nCurrentParameter = OUTNAME; 
break; 

case OUTNAME: 

s t r c py ( s z Out put F i I e, a r g v [ i ] ) ; 
n Cu r r e n t Pa r a met e r = WI DTH; 
break; 

case WI DTH: 

s s ca nf ( a r g v [ i ] , "%d", &nTemp Wi dt h) ; 

i f ( nTempWi dth < 20 | | nTempWi dth > 128) 

{ 

Gi veHel p( BADWI DTH, NULL); 

} 
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else 
{ 

nLi neWidth = n T e mp Wi d t h ; 

} 

nCur rent Parameter = L AS T _ T H I NG; 

break; 

d e f a u I t: 

Gi veHel p( BAD_ PARM, NULL); 
break; 

} 



Statemachines can prove valuablein helping to organizeyour programs. Theuse 
of a state variable was a logical choice as a method to keep track of where I was i n the 
program's command lineand to track which parts of the required command param- 
eters had been processed. 



Summary 

In this chapter, you learned about command linearguments, pointer arrays, function 
pointers, and statemachines. 

• Each program ispassed, as parameters to the ma i m ) function, the command 
line parameters. 

• Command line parameters are processed by the operating system, by being 
parsed into separate tokens. 

• You can obtain thenameof your program (the executable file's name) using 
the parameters passed to ma i n ( ) . 

• Like data objects, functions can have pointers to them. 

• Like any other pointer, a function pointer can be placed in an array and 
indexed using an index variable. 

• Function pointers can be passed as parameters to other functions, which then 
can call these functions. 
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• Properly designed menu-driven programs can offer an excellent user interface. 

• It generally is not worth the effort to design your own menu system. Using 
Windows, OS/2, theM acintosh, XWindows, or some other commercially 
available menuing system is a much better choice. 

• Using state machines enables you to efficiently design a program that must 
process data in either a fixed or random format. 
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By now, you probably have realized thatcomputersdon'tsavenumbersin memory in 
thesameformatashumansdo.TheCPU convertsa number that thecomputer's user 
provides to a format that the C PU better understands. This conversion, transparent 
to both the user and the programmer, enables the computer to work efficiently. 



Decimal 

We work with decimal (base 10) numbers. Decimal numbers have become popular 
primarily because we, as humans, usually have ten fingers. Yes, it'strue, our number 
system isbased on counting on our fingers. W hy, then, don't weusebase5, (thefingers 
on one hand), or base 20 (both hands and feet)? 
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D ecimal numbers have become so natural to usethat weno longer stop to think 
about theconcept of what weare doing. Weadd, carry, subtract, multiply, and divide 
with ease (most of usdo, anyway) and don't stop to consider any other based number 
systems; when we are asked whether we use any of these other systems, most people 
reply "N o." T he next most common system, however, is base 60— time, where 60 
secondsmakea minute, and 60 minutesmakean hour. W edon't get shaken when we 
arepresented with timecomputations; when wehaveto convert to or work in number 
systems other than decimal, however, our palms sweat and we get the shakes. 

Let's review the decimal number system. First, decimal numbers have the 
characters to represent items. Figure 5.1 shows the first ten digits and what they 
represent. 



Character 


Value 


0 




1 




2 




3 




4 




5 




6 


« ♦ * f '^tf-" 


7 


♦ ♦ * * * * « 


8 




9 





Figure 5.1. Decimal numbers 0 through 9. 

Thefirst useof numbers was probably to countfood stocks, livestock, and other 
objects encountered daily. As shown in Figure 5.1, a problem begins when you have 
more than nine objects. T hings get difficult then: Should new digits be created, ora 
new system? 

When thedecimal system was developed, someone decided that ten characters 
(or digits) were sufficient and that a system had to be created to indicate how many 
handstherewereto represent theobject being counted— thetenscolumn was created. 
It then waspossibleto write, using two digits, numbersthat were ten ti m es as I arge as 
before. N o one realized that there would ever be a need for a number larger than 99. 
(After all, thegreatest number of fish ever caught at a singletime probably was only 
18). Thedecimal number system was born, capable of representing as many as 99 
objects. 
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Then Joe came along. Brighter than most, heinvented thefishing net. H eforgot 
to patentthefishing net, and soon a number of cheap but usableclonefishing netswere 
available. Bob, who bought one of the better clones, managed onedayto catch much 
morethan 99 fish. H ewenthomeand proudly announced thathiscatch was"99 and 
many more," to which hisloving wifewanted to know how many more. T hehundreds 
column then wascreated. Bob'swifesimply carried theconcept of thetenscolumn out 
to a new column. And so it went— soon thousands, millions, and (when government 
was created) billions were only a short way off. 

All of thismath, using thedecimal number system, could bedonewith thehelp 
of the oldest digital computer, the hand. 

Binary 

Digital computers, invented later, didn't have hands. They used memory to store 
numbers. This memory, which lacked fingers, could hold only a zero (nothing) or a 
one(something). Any number greater than onecouldn'tberepresented within asingle 
computer memory location. (I'm ignoring the analog computer, which could store 
morethan zero and onein a singlememory location— they never became popular and 
are n ot w i d el y avai I ab I e tod ay) . 

After thef irst few hoursof working with zero and one, it was apparent that a way 
to represent numbers larger than one had to be developed. This task wasn't difficult 
because designers and engineers are bright folks, and a scheme of using consecutive 
locations in memory was quickly developed. 

Because only two states existed in a singlememory location, the representation 
of numbers with computers was called binary. The use of this word is common with 
computers: Computers sometimes are referred to today as binary computers To a 
computer, binary is as natural as decimal is to humans. Computers have no problems 
counting, doing math, storing, and performing I/O using binary numbers. The 
representation of binary numbers, however, left much to bedesired. For instance, the 
year 1992 can berepresented using only four digits with thedecimal number system; 
in binary, it isrepresented asiimooiooo (11 digits). Thisnumberisnot nearly aseasy 
for humans to work with, write, or understand. 

LookatFigure5.2toseehowthebinaryvalueforl992isdetermined.Thisfigure 
shows the binary value, the value of each bit, and thedecimal result. 
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0 0 



102 4 * 


1 




102 4 


512 * 


1 




512 


256 * 


0 




256 


12 8 * 


1 




128 


64 * 


1 




64 


32 * 


0 




0 


16 * 


0 




D 


8 * 


1 




8 


4 * 


0 




0 


2 * 


□ 




D 


1 * 


□ 




0 


(decimal) 1992 



0 0 0 (binary) 



Figure 5.2 The year 1992 in decimal and binary. 



Hex 

Computers did not always have an 8-bit block of memory defined. Early computers 
used 10, 11, and 16 bits, and other computers probably weredevdoped that had every 
other possible number of bits. 

H ex is the compromise that enables both computers and people to understand 
number representation. Thehex number system isbased on 16. M y guess is that the 
word hex was adopted because the base was 6 greater than base 10. H ex adds a new 
wrinkle: Binary usesonly 2 digits, 0 and 1; decimal uses 10, 0 to 9; hex, however, uses 
16 numeric digits. Because you don't have 16 digits, either 6 new characters must be 
created to represent the new numbers, or you must use 6 existing characters. 
Introducing 6 new characters into the currently used character set isn't easy, but 
reusing 6 other characters is easy. 

The developers of hex notation chose to use the characters A through F for the 
new digits (see Figure 5.3). N o standard exists for whether the digits are represented 
in upper- or lowercase; I prefer uppercase, however, because numeric characters give 
the appearance of being uppercase (or larger) characters. 
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Character 


Bit positions 


Value 


0 


0000 




1 


0001 


• 


2 


0010 


*** 


3 


0011 


#*•*• 


4 


0100 




5 


0101 




6 


0110 


****** 


7 


0111 


************** 


8 


1000 


**************** 


9 


1001 




A 


1010 


rrr* ***** * 


B 


1011 




C 


1100 




D 


1101 


«* *-*• # *••*• **# # r *- *-•*•' 


E 


1110 




F 


1111 


tf********^***************^**** 



Figure 5.3. H ex numbers 0 through F. 

Because most of thedevelopment of computers was done in countries that used 
the Roman alphabet, the choice of the number of bits in a computer's word general- 
ly was determined by the number of characters thecomputer could recognize. As the 
computer was being developed, a number of systems to organize the characters and 
assign each to a numeric value already were in existence. The minimum number of 
characters wasfairly large: It was necessary to haveletters— both upper- and lowercase 
(52), numbers (10), punctuation and symbols (about 20), which brought thetotal to 
between 80 and 90 characters. 

In binary number systems, the number of bits increases in the following 
progression: 1, 2, 4, 8, 16, 32, 64, 128, 256, and soon. M ost people quickly realized 
that 64 (a 6-bit word) wastoo small, 128 (a 7-bit word) was much better, and that 256 
(an 8-bit word) was all that would ever be needed. Obviously, this artificial limit was 
based on current needs, with no consideration of thefuture. Sixteen bits now areused 
to represent characters in some applications. 

Eight bits generally was accepted for the size of the basic block of computer 
memory. This amount was referred to as a byte; the origins of this word, however, 
escape me. 
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Hex might have been developed as a compromise between binary, required for 
thecomputer, and decimal, required for programmers. Two hex digits can beheld in 
the standard-size computer memory, which is eight bits. 

Theexampleof 1992 becomes7C8 when it is represented in hex. This number, 
which is not as long as its decimal equivalent (it has only three digits), is almost as 
indecipherableas the binary. It isn't necessary to beableto read hex numbers to bea 
good programmer, but it helps. 

Toseehowthehexvaluefori 9 9 2 is determined, look at Figure 5. 4. Itshowsthe 
hex value, the value of each digit, and the decimal result. 

0 * 4096 = 0 

7 + 256 = 17?2 

12 * 16 = 192 

8 * 1 = 8 



(decimal) 1992 



0 7 C 8 < hex > 
Figure 5.4. The year 1992 in decimal and hex. 



Octal 

Octal, the base 8 number system, enjoyed great popularity on a number of DEC 
computers, primarily thePDP-8. Trust me, though, octal isdead. Don't useit, because 
no one else uses it anymore. Some computers used word lengths that were not 8 bits 
(a byte) long. Rather, they used a 12-bit word that easily wasdivided into 4 octal digits 
of 3 bitseach. U nlikehex, which hasmorethan 10 characters, octal has only 8, which 
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makes the decimal-number characters fully usable. Octal is used for D EC minicom- 
puters, and C was developed on DEC minicomputers— therefore, the support for 
octal. Figure5.5 showsa representation oftheoctal numbers, which aresimilar to the 
ones in the decimal-based systems; octal, however, doesn't have numbers 8 or 9. 



Character 


Bit pattern 


Value 


0 


000 




1 


001 




2 


010 




3 


011 


* * • 


4 


100 




5 


101 




6 


110 




7 


111 


£ • £ £ 



Figure 5.5. Octal numbers 0 through 7. 

When thei 99 2 example is represented in octal, it becomes 3710. This rather 
misleading number is as long as its decimal equivalent (and could have been longer). 
Without some form of prefix (or postfix) notation, you have no way to determine 
whether any number is octal- or decimal-based (3710 is a legitimate number). 

Look at Figure5. 6toseehowthat octal valuefor 1992 isdetermined.Thisfigure 
shows theoctal value, thevalueof each digit, and thedecimal result. 

I 3 * 512 = 1536 

I 7 * 64 = 448 

I 1 * B — 8 

I 0 * 1 = g_ 

(decimal)1992 



3 7 10 (octal) 

Figure 5.6. The year 1992 in decimal and octal. 
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Looking at a File 

I n any program that writes a filethat is not pure text, you must ableto look at thefile 
and determine whether the program has written the file properly. When you run the 
DEBUG utility, a crude debugger, on thePC, it enables you to dump programs and 
data files. Because the program is difficult to use, however, it is not used often. 

Onesolution istohavea program that dumps files and provides both ahexand 
ASCII listing of thefile'scontents(seeListing 5.1,). DUMP isasimpleprogramthat 
reads files of any length and lists their contents in an easy-to-use format. 



Listing 5.1. DUMP.C. 

/* DUMP, written 23 May 1 9 92 by Peter D. Hipson */ 
/* A program that dumps files in hex and ASCII. */ 



tinclude < s t d i o . h > // Make includes first part of file 

#i n c I u d e <string.h> // For string functions. 

#include <stdlib.h> // Standard include items. 

#i n c I u d e <process.h> // For exit(), etc. 

tinclude <t i me . h > // For time information. 



#define ARG_ HELP '?' 
#define ARG_ SLASH '/' 
#define ARG_ DAS H 



int ma i n ( // Define ma i n ( ) and the fact that 

int argc, // this program uses the passed parameters, 
char * a r g v [ ] , 
char * e n v p [ ] 
) ; 



int ma i n ( 

int argc, 
char * a r g v [ ] , 
char * e n v p [ ] ) 



{ 



FILE *f pFi I ePoi nt er ; 
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I ong 



I P o s i t i on; 



i nt 



i ; 



i nt 



i nt 



nNumber Byt es Read; 



u n s i gned 



i nt n Hex Nu mbe r ; 



char 



* ps z Temp ; 



/* strings for _splitpath() (which parses a file name) */ 

char szDr i ve[ _ MAX_ DRI VE] ; 

char szDi r[_MAX_DI R] ; 

char s z F n a me [ _ MAX_ F NAME ] ; 

char s z Ex t [ _ MAX_ EXT] ; 

char szl nputFi I e[ 128] ; 

char szProgram] 132] ; 

char szBuffer [ 132] ; 

char sBuffer[ 257] ; 

t i me _ t t T i me ; 

struct t m * pTM; 



_s pi i t pa t h( a r g v[ 0] , 
s z Dr i ve , 
s z Di r , 
s z F n a me , 
szExt ) ; 

strncpyl szProgram, szFname, sizeof(szProgram) ■ 1); 

if ( ar gc <= 1) 

{ 

p r i n t f ( " %s : - No file n a me g i v e n . \ n " , szProgram); 
exi t ( 4) ; 

} 

for (i = 1; a r g v [ i ] ; i+ + ) 



continues 
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Listing 5.1. continued 



if ( a r g v [ i ] [ 0 ] == ' / ' | | a r g v [ i ] [ 0 ] == ' - ' ) 

{ /* You have an argument, convert to lowercase, and test. */ 
pszTemp = s t r I wr ( a r g v [ i ] ) ; 

for ( j =1; j < st r I en( pszTemp) ; j ++) 

{ 

swi t ch( pszTemp! j ] ) 

{ 

case ARG_ HELP: 

pri ntf( "Usage: %s f i I e n a me . e x t \ n " , 

s z P r o g r a m) ; 
exi t ( 4) ; 
break; 

case ARG_ SLASH: 
case ARG_ DASH: 
break; 

d e f a u I t: 

pri n t f ( " %s : - Invalid option ' %c ' . \ n " , 

psz Tempi j ] , 

s z P r o g r a m) ; 
break; 



} 

} 

} 

else 

{ /* Either a filename or width. */ 
s t r c py ( s z I n p ut Fi I e, a r g v [ i ] ) ; 

} 



if ( (fpFi I ePoi nter = f op e n ( s z I n p ut F i I e, "r+b")) == NULL ) 

{ 

pri n t f ( " %s : Unable to open file: %s \ n " , 
s z P r o g r a m, 
szl nput Fi I e) ; 
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exi t ( 16) ; 

} 

I Posi t i on = 01 ; 

pri ntf( "\ n") ; 

t i me ( &t T i me ) ; 

p T M = I o c a I t i me( &t Ti me ) ; 

/* format a time string, using s t r f t i me ( ) (new with ANSI C) */ 

s t r f t i me ( s z B u f f e r , 
si zeof( szBuffer) , 
"%A %B %d, %Y at %H: %M: %S", 
pTM) ; 

pri ntf( "Dump of %s , %s\ n\ n " , 
s z I n p ut F i I e, 
szBuffer ) ; 

wh i I e ( ( n Nu mb e r By t es Rea d = f r e a d ( ( c h a r *)sBuffer, 
sizeof(char), 16, fpFilePointer)) > 0) 

{ 

pri ntf ( " %8. 8X ■", I Posi ti on) ; 

for ( i =0; i < 16; i + + ) 

{ 

if ( i ==8) 

{ 

pri n t f ( " - " ) ; 

} 

else 

{ 



i f 



0 I 
4 I 
12) 



continues 
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Listing 5.1. continued 

printff* "); 

} 

} 

i f ( i < nNumber Byt esRead) 

{ 

nHexNumber = (unsigned c ha r ) s B uf f e r [ i ] ; 
p r i n t f ( " %2 . 2 X " , (unsigned i n t ) n Hex Nu mbe r ) ; 

} 

else 

{ 

printff" " ) ; 

} 



for (i = 0; i < nNumber Byt es Read; i + + ) 

{ 

if ( sBuf f er [ i ] < ' ' 

sBuf f e r [ i ] == ' \ x F F ' ) 

{ 

sBuf f er [ i ] = ' . ' ; 

} 

} 

s Buf f er [ n Nu mber By t es Rea d] = '\0'; 

p r i n t f ( " : %s " , s B u f f e r ) ; 

p r i n t f ( " \ n " ) ; 
I Pos i t i on += 16; 

} 

r et u r n ( 0 ) ; 
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DU M P.C has few unusual parts. The first part of the program is the same 
command line arguments parser from Chapter 4, "Special Pointers and Their Use," 
with a test for thehelp option (standardized as/ ? under DOS on the PC). DU M P has 
no other options and simply requires the name of thefileto dump. 

Thefile is opened and read in 16 bytes at a time (or less, if fewer than 16 bytes 
remain in thefile). T hebuffer, with 16 bytes, iswritten out, first in hexformat and then 
in ASC 1 1 format (with control characters, and a . character substituted for D EL. 

DUMP enables you to look at afile'soutput; you still must understand what the 
output means, however. 

Therearetwo ways to store integers in memory. Thefirst method, in which the 
high-order bits are stored in the low byte or bytes, makes dumps easy to read; in the 
second method, the low-order bits are stored in the low byte or bytes. One method 
makesit easier for you to look at adump and determineaninteger'svalue, and theother 
method makes you work a little harder. T he PC , of course, makes you work harder; 
supposedly, it makes theCPU faster, but we'll never know. Figure 5.7 shows both a 
16-bit integer and a 32-bit integer, as they are stored in the PC's format. 





f 






r 












r 






> 
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OD 
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07 


0 0 


48 


65 


6C 


6C 


6F 


00 


48 


FC 


2F 


01 
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nVear = 1992 (or 0x07C8)' 

szHello[] = "Hello"; (with NULL at end)' 
lYearYear = 19921992 (or 0x012FFC48)- 



Notice that the text strings are not byte swapped, 
even if integers are. 

Figure 5.7. Integers in memory (16 and 32 bits). 



The method your CPU uses to store integers must always be considered 
whenever you are viewing memory directly. If you do not know the order of the bits 
in storage, the simple program in Listing 5.2 tells you which method is being used. 
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Listing 5.2. WCHBYTE.C. 

/* Program WCHBYTE, written 25 May 1 99 2 by Peter D. Hipson */ 
/* Programthat shows byte swapping (if present) by the CPU. */ 



tinclude < s t d i o . h > // Make includes first part of file 

#i n c I u d e <string.h> // For string functions. 

#i n c I u d e <stdlib.h> // Standard include items. 

#include <process.h> // For exit() etc. 



int ma i n ( // Define ma i n ( ) and the fact that this programuses 

i nt a r gc , / / the passed pa r a met er s . 
char * a r g v [ ] , 
char * e n v p [ ] 
) ; 



void NonPrint(const char chChar; 

void Letter(const char chChar); 

void Number! const char chChar); 

void Space( const char chChar ) ; 



int ma i n ( 

int a r g c , 
char * a r g v [ ] , 
char *envp[ ] 
) 



{ 



unsi gned char cTempl 10] ; 

unsigned char *pcTemp; 

int nYear = 1992; 

I ong i nt I YearYear = 19921992; 

char s z H e I I o [ ] = "Hello"; 



pcTemp = (unsigned char * ) & n Y e a r ; 
cTempl 0] = * ( pcTemp + + ) ; 
cTempl 1] = *( pcTemp) ; 
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printf("nYear = %d decimal, %4 . 4 X hex, in memory %2 . 2 X %2 . 2 X \ n " , 
n Y e a r , 
n Y e a r , 
cTempl 0] , 
cTempl 1] ) ; 



pcTemp = (unsigned char *) &l YearYear; 
cTempl 0] = * ( pcTemp+ + ) ; 
cTempl 1] = * ( pcTemp+ + ) ; 
cTempl 2] = * ( pcTemp+ + ) ; 
cTempl 3] = * ( pcTemp) ; 



pri n t f ( "I YearYear = %l d decimal %8 .SIX hex, in memory %2 . 2 X %2 . 2 X \ 
%2, 2X %2, 2 X \ n " , 
I YearYear, 
I YearYear , 
cTempl 0] , 
cTempl 1] , 
cTempl 2] , 
cTempl 3] ) ; 



pcTemp = 
cTempl 0] 
cTempl H 
cTempl 2] 
cTempl 3] 
cTempl 4] 
cTempl 5] 



unsigned char 
= * ( pcTemp+ + ) 
= * ( pcTemp+ + ) 
= * ( pcTemp+ + ) 
= * ( pcTemp+ + ) 
= * ( pcTemp+ + ) 
= * ( pcTemp+ + ) 



ol 0] ; 



&s z He I 
H 
e 
I 
I 

o 

\ 0 (NULL) 



pri ntf( "szHel I o = ' %s ' (string), in memory ' %c' ' %c ' ' %c ' ' %c ' ' %c ' \ 
' %c ' \ n " , 
s z He I I o , 
cTempl 0] , 
cTempl 1] , 
cTempl 2] , 
cTempl 3] , 
cTempl 4] , 
cTempl 5] ) ; 



r et u r n ( 0 ) ; 

} 
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I f thehex representation andthememoryviewofthevariablesarethesamewhen 
you run WCH BYTE, dumps madeusing D U M P will becorrect. If they aredifferent, 
however (which isthecasefor all PC s), you haveto swap thebytesmanually when you 
are using a DUM P listing. 

Bit Operators 

Bit operators form the basis for C's powerful bit-manipulation capabilities. Never 
confuse these operators with their logical counterparts, which work on different 
principles. lnTable5.1,thekeywordTRUE signifiesatruebit (or bits) that isset to one, 
and false signifies a bit (or bits) that isset to zero. 

Table 5.1. Bitwise operators. 
Operator Description 

& Performs a bitwise AN D operation. If both operands areTRUE, the 

result isTRUE ; otherwise, theresult is f al s e . 

Performs a bitwise OR operation. If either operand is true, the 
result Sstrue ; otherwise, theresult is f al s e . 

Performs a bitwise exclusive OR operation. If both operands are 
true or both operands areFALSE, theresult is f al s e . T he result is 
true if oneoperand Sstrue and theother is f al s e . ExclusiveOR is 
used to test to see that two operands are different. 

« ShiftstheX operand, Y operand bitsto the left. For example, (1 « 

4) returns a value of 8. In bits, (0001 «4) results in 1000. New 
positions to the left are filled with zeroes. T his is a quick way to 
multiply by 2, 4, 8, and so on. 

» ShiftstheX operand, Y operand bitsto the right. For example, (8 

»4) returns a value of 1. In bits, (1000 »4) results in 0001. New 
positionsto the right are filled with ones or zeroes, depending on 
thevalueand whether the operand being shifted is signed. This is a 
quick way to divide by 2, 4, 8, and so on. 

Returns the l's complement of the value. The l's complement is 
defined as setting all bits that are 1 to 0, and all bits that are 0 to 1. 
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Do not confuse the bitwise operators with the logical operators. The misuse of 
these operators can cause problems that are difficult to repair, such as those in the 
following program fragment: 

i nt x = 1 ; 
i nt y = 2 ; 

// Using a logical AND: 

i f ( x && y ) 
{ 

// With x == 1, and y == 2, this will ALWAYS be TRUE. 

} 

// Using a bitwise AND: 

if (x & y) 
{ 

// With x == 1, and y == 2, this will NEVER be TRUE. 

} 

Whydoesthebitwisetestfail inthisfragment?Theansweriseasy, butonlyifyou 
look at the bits themselves. T he bit pattern for x is o o o o o o o 1 , and the bit pattern for 
y isoooo oooio. Doinga bitwise and shows the following: 

0000 0001 & 0000 0010 = 0000 0000 

P racti ce i s on e of the best teach ers— practi ce usi n g th ese operators to get a better 
feel for how they work. The following section discusses the use of these operators, 
including some example code fragments. 

Bit Fields 

A bitfield is a data object being accessed at the bit level. These fields, which maybe 
only onebit long, haveforeach bit adefined meaningthat mayor may not be related. 
A good programming practiceisto makeall thebitsin asinglebitfidd variable-related 
so that management of thebitfidd iseasier. W hen you areusing AN SI C , you generally 
can have a maximum of 16 bits in a bit-mapped variable. There are two ways to use 
bitfidds: 
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1. Assign a meaning to each of the bits of any integer variable. 

2. With a structure, you may create a bit field that is any length (to a maximum 
of 16 bits). 

Let's look first at user-defined bitfields. When you declare an integer variable, 
such asthefollowing: 

unsigned short int nFlag = 0; 

thecompiler allocates a 16-bit short integer and initializes it to zero. T his example is 
less than meaningful for bit flags. Toharnessthepower of a bit flag, you haveto define 
each bit position and beableto test, set, and reset each bit without regard totheother 
bits. You know that you havel6 bitsto work with, but you don't know how to address 
them.Thisprocessisn'tasdifficultasitmightseem,becauseeach bit hasa logical value, 
and working with these values is easy. 

Figure5.8 shows the bits in the variable. You can easily determine (and assign) 
a meaningful flag for each of these bits, such as shown. 

unsigned short int nFlags = OkFFFF; 

(bit position) 

^ ^ ^ 1 1111 ( bit value ) 

' 01 

1 02 

1 04 

1 08 

10 

1 20 

1 40 

1 80 

Figure 5.8. Bit values in a 16-bit integer. 

Figure 5.8 shows that you use the value 4 to access the third bit from the right. 
Assume that if this bit is set, it tells you the user has a middle name, and if it is not 
set, theuser doesn't haveamiddlename. You first makeadefined identifier so thatyour 
program is manageable: 

#d e f i ne Ml DDL E NAME 0x04 
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You use the hex value because it's easiest to remember and use. The decimal 
equivalents are not that usable. Assign thefirst bit from theleft to tell you thattheuser's 
middle name is just an initial: 

tdefine MIDDLEINITIAL 0x80 

N ow th at you havesom edef i n es, I et's I ook at h ow to u seth em . F i rst, you can cl ear 
all flagsin theflag variablen f i ag by simply assigning a zero to it: 

n F I a g = 0; 

To set theflag so that you knowthattheuserhasamiddlename,you can use the 
following line: 

n F I a g | = Ml DDL E_ NAME ; 

T hisstatement usesoneof C 's bit operators. T heseoperatorssddom areused by 
most programmers, primarily because they are not well understood. This is a shame 
because they make management of logical information much easier. 

Next, suppose that the person's middle name is only an initial. You set both the 
mi ddl e name flagand theMi ddle i ni ti al flag. You can useoneassignment or combine 
both: 

n F I ag = ( Ml DDL E_ NAME | Ml DDL E_ I NI TI AL) ; 

This statement could have been written as 

n F I a g = ( Ml DDL E_ NAME | Ml DDL E_ I NI TI AL | n F I a g ) ; 

I f theflag bits wereal ready set for some reason, they don't change. After they are 
set, performing a bitwiseoR on them doesn't change their state. 

N ow assumethat you set themiddle-nameflag, but later you must change it to 
indicatethatthereisno middle name(or initial). BecausetheoR only sets (and doesn't 
reset), you have to do something different: 

n F I a g &= ( -Ml DDL E_ NAME & -Ml DDL E_ I NI TI AL) ; 

This statement introduces both theone'scomplement operator - and the bitwise 
and operators,. You haveused theoNES complement operator to invert the identifier's 
bits. For example, if the identifier's bit pattern (as mi ddle name's) is 

0000 0100 

the result of the - is 

mi ion 
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This bit flag, when it is combined using the bitwise &, enables you to turn off a 
bit in then Flags variable. T h i s effect isimportant because setting and resetting thebits 
is a common operation. 

Finally, you must test bits. You want to test only those bits that are significant 
for whatever we are testing. For example, to see whether there is a middle name (the 
mi ddl e_ name flag is set), you can use the following test: 

if ( ( n F I a g & Ml DDL E _ NAME) ) 

I n thistest, several things are important. You must becareful notto usethelogical 
and operator (&&) when you intend to use the bitwise one. Also, you should use 
parentheses around each bitwiseoperation so that the order of precedence is clear. In 
the preceding test, the expression yields a nonzero value if the bit is set, or a zero if it 
is not. You can test two bits at onetime using either 

if ( ( n F I a g & ( Ml DDL E_ NAME | Ml DDL E_ I Nl T I AL ) ) 

or 

if ( ( n F I a g & Ml DDL E_ NAME ) && 
( n F I a g & Ml DDLEI Nl Tl AL) ) 

Becauseeither expression iscorrect, which oneyou useisprobablymoreamatter 
of programming stylerather than efficiency. Just makesurethat you areclear about the 
order in which the expression is evaluated; when in doubt, use parentheses. 

Summary 

In this chapter, you learned about decimal, hex, binary, and octal notation. You 
learned also about bit field usage. 

• Decimal (base 10) isthenumber baseweusein everyday life. 

• H ex (base 16) most commonly is used by programmers in writing software. 
Some programmers can do hex addition and subtraction without the aid of a 
calculator. 

• Binary (base 2) is the only base the CPU understands directly. All other 
number systems must be converted to binary for the C PU 's use. 



158 



Decimal, Binary, Hex, and Octal 



• Octal, originally developed for DEC'S PDP-8 computers, seldom is used by 
today's programmers, primarily because octal worked best with 12-bit-word 
computers. 

• C supports six bitwise operators, enabling direct manipulation of bits by the 
programmer. 

• U sing bit fields, programmers can store much information by using individual 
bits. 
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N ot all programs are as simple as the examples in this book. Rarely do you write a 
significant program that has only a single source file; if you do, it usually is too large 
to be maintained easily. Whether your program is huge, with hundreds of thousands 
of lines, or is a smaller one, with only a few thousand lines of code, you can benefit 
from using separate source files. 

Someof theinformation in thischapter isbased on M icrosoft's tools, such asits 
M AKE utility and the L I B program. If you arenot using M icrosoft's products or are 
not even using a PC, much of the discussion in this chapter will be very helpful 
because it is information that is new to you. 
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Compiling and Linking Multiple Source Files 

T herearea number of reasonsto havemorethan onesourcefile. T he most important 
reason is to help keep your program's source organized. Without this organization, as 
the program grows larger, it becomes increasingly more difficult to maintain. 

Becausetherearefewrulesregardingthesubdivision ofsourcecodebetween files, 
how do you determinewhattoputin each file? First and foremost, themajorityof the 
programswritten don't start out large. M ostsoftwaredevdoperscreateashdl for their 
programs (using the ma i n( ) function) and then build the user interface and the 
program 's f u n cti on al i ty u si n g cal I s f rom ma i n ( i . T h i s p rocess al I ows th e devel oper to 
test and debug small parts of the program with thehopeof not creating new problems 
for other parts of the program. 

Prototyping is a technique for writing larger (and smaller) programs. Don't 
confusethisuseof prototyping with C 'suseof it. Prototyping a program requires that 
you do (and have) a number of things, including thefollowing: 

1. Establish the program's basic functionality. You must do this by working with 
the program's final users. 

2. Select an operating environment— whether it's a standard character- based 
application (becoming increasingly rare) or a graphical user interface (GUI) 
Windows-based program such asM icrosoft Windows or IBM Presentation 
Manager. Pay particular attention to whether the program will use graphics (a 
G U I interface is a necessity), whether it will be mass marketed (or is intended 
for a very small vertical market), and whether the users with whom you are 
working will be the same users that use the program later. 

3. After the program's basic functionality and operating environment have been 
selected, the user interface then is developed. The user interface is the most 
important part of the program. In a GUI program, follow standards that 
already have been established, including M icrosoft's guidelines and IBM 's 
book Systems A ppli rati on Architecture Common User Access Advanced Interface 
Design Guide Resist the urge (and pressure from others) to do your own thing 
when you are writing GU I Windows applications. A prime example is a 
program for M icrosoft Windows that, although it's a good application, has a 
nonstandard user interface that makes using it nearly impossible if you are an 
experienced W indows user. 
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4. After the basics of the user interface are developed (at this point there probably 
won't be much functionality), potential users should review the interface and 
suggest additional functionality. 

5. Create and implement the standard parts of the user interface, such as the 
capability to open, close, and save files. Create the help access. Create the look 
and feel of the application's screen. You probably won't ever face a "look and 
feel" lawsuit, and the standards make it easier for users to becomefamiliar with 
your program. The fewer unique things the user must learn, the less support 
you have to provide. 

6. Add each of the functionalities, oneatatime, that the program requires. Each 
can have its own source fileand should be fully self-contained. Don't use too 
many shared supporting functions: W anting to change a supporting function 
is common, but problemsoccur when somecallsto these functions then fail. 
Utility functions— the building blocks of your programs— should be as simple 
as possible. 

Suppose that you have a large program, which therefore is divided into several 
source files. H ow do you put the pieces of the program together and create a single 
program that runs?T he process of creating a large, multisource file program is shown 
in Figure 6.1. It shows generically what you must do (at a minimum) to create a 
multisourcefileprogram.You first com pi leal I of your sourcefiles and then link them. 



( Start ) 



■■■ 




■- 




Compile a 
source file. 




/MoreXyes 



files? 



Tno 
Link 



Figure 6.1. A multisource file program. 
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Compiling Multifile Programs 

Compiling a multifile program isn't much moredifficultthan compiling a single-file 
program. M any compilers can perform thecompileand link using asinglecommand, 
usually either cc orcL ; other variation sexist, however. You must tell thecompiler that 
it should not link the program when it does the compiling. You tell it (with the 
M icrosoft compilers) by usingthe/ c option, which simplyspecifiesthatyou wantonly 
a compile. 

A couple of things are necessary in creating a functioning multisource file 
program: 

• Besure that you have properly defined each variablethat will be shared 
between different parts of the program, using the extern keyword. 

• Be sure that all functions have a single sharable prototype the compiler can use. 
N ever create more than one copy of the prototypes: M ake a si ngle copy and 
place it in a shared header file (this subject is discussed in this section). 

Because function parameters and shared variables (to a lesser extent) are the 
primary methods of passing information among different functions in the program, 
by defining them properly you increase the likelihood that the program will run 
properly. 

Because you don't yet have an automated system to control which of the source 
files is compiled (don't try to remember "I changed this one, but not that one"), you 
mustcompileeach sourcefile. For p rojects that haveonly a few source files, compiling 
each one isn't as bad as it seems; if you have several hundred source files, however, 
compiling all ofthemeverytimeachangeismadeisalittleexcessive. Later, the"U sing 
MAKE Files" section discusses automated project systems and how to make your 
program creation more efficient. 

Linking Multifile Programs 

W hen you arelinking a program, the linker requiresa minimum (other than options) 
of thenameof thecompiler output .OBJ fileThisnamethen isusedfortheexecutable 
program's name (which has an EXE extension under DOS on the PC). If more than 
one object file is specified, the first file's name is used if no executable filename is 
specified. 
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Thelinker, whose command linecan belengthy, acceptsamultilinecommand 
line. You typethefirst line and end it with a plussign (+) and a return. Thelinker then 
prompts for the next part of the command line. This process of continuing the 
command linecan continue for as long as necessary. 

The following short code fragment shows a typical larger multisource file 
program'slink command. (You shouldn't havemultiplelineswith comments in a real 
command). 

link / I i nenumbers / a I : 16 /nod /map + / * Linker options */ 

mainprog.obj f i I e 2 . o b j f i I e 3 . o b j , + /* Compiler output obj */ 
mainprog, + / * Executable file's name 



The i i nk command has a number of options (all of which probably will be 
different for other linkers). These options tell the linker to include line number 
information for the debugger (/i i nenumbers), align objects on 16-byte boundaries 
(/a i : 16), not use thedefault libraries (/ nod) that thecompiler inserts in theO BJ files, 
and create a load map used for debugging (/ map). 

After the options are the input 0 BJ files. You can generally omit the 0 BJ 
extension. You can specify as many 0 BJ files, separated by blanks, as you want. If 
several OBJ files are needed, you may have to use the multiline command format. 

T hen the name of the output file is specified. This filename receives the EXE 
extension if noextension isspecified. If no output filenameisprovided,theexecutable 
filename is derived from the name of the first 0 BJ file. 

Thenext parameter isthenameof thelinker map file. T hisfile (seeC hapter 16, 
"Debuggingand Efficiency," for an example) isuseful for debuggingyour program and 
for certain performance considerations. If you don't specify a filename and the/ map 
option is specified, the map filename is derived from the executablefile's name. 

Thefinal parameters are the libraries. This parameter (like the input OBJ files) 
can have more than one name, separated by blanks. If you have specified the/ nod 
option, you must specify all thenecessary libraries; otherwise, it is necessary to specify 
only the libraries that arespecial to this program. It is not an error to specify a library 
that is not needed, and the linker does not load extra code if an unneeded library is 
specified. 



ML I BCEW LI BW STARBOTH STARAE 



+ / * No map file specified */ 
+ / * Libraries */ 
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Using include 

Thepreprocessor's#i nci u de statement isa powerful part of creating a C program. You 
cannot createa program that compiles without warningsif you do not use at least one 
#i nci ude statement. A set of i nci u d e filesissupplied with everyC compiler. Thesefi I es 
alwayshavethe.h extension, which isshorthand for headers. TheAN SI C definitions, 
prototypes, and other necessary information thecompiler needsto function properly 
are contained in these files (see Chapter 13, "All About Header Files"). 

The#i nci ude statement can becoded in two formats. Each is slightly different; 
the differences, however, are easy to understand. The first format is 

#i nci ude " s t d i o . h " 

In this format, the file to be included is delimited by the - character. The 
delimiter i n this #i nci ude statement means: "When thecompiler searches for the file 
to be included, the search starts with the current directory of the file that has the 
#i nci ude;ifthefileisnotfoundandthefilecontainingthe#i nci ude isalso an included 
file, then it's a parent." This process continues recursively until all directories in the 
chain of included fileshavebeen searched. I f thefi lesti 1 1 hasnot been found, thesearch 
continues as though the second format has been specified. The second format is 

#i nci ude < s t d i o . h > 

I n thisformat, thefileto beincluded isdeNmited by the< and > characters. W hen 
thecompiler searches for thefileto beincluded, thesearch starts with the directories 
specified on thecompilecommand line(using the/ 1 option) and then the directories 
specified using the environment variable i nci ude. The current directory is not 
searched unless it has been specified in oneof these two places. If thefilecannot be 
found, thecompiler issues an error message and the compile ends. 

You know that you mustincludeC'sheader files because they have thef unction 
prototypes and other defined identifiers needed to writeyour program. W hat elsecan 
beincluded?An include filecan contain anything that could havebeen put in a source 
file. You can havepreprocessor statements, C sourcecode, and so on, and thecompiler 
treats theinformation as though it all werein thesamefile Theonly differenceisthat 
when an error isin an i nci ude file,thecompiler'serrormessageprovidesthenecessary 
nameand linenumber of the i nci ude file. 
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For large projects, I generally recommend that you have the foil owing custom 
include files. Although some projects do not need all these files, you can create and 
include them at any time. 

• T hefirst file is named with the same name as the program. This file has only 
i nci ude statements and looks like Listing 6.1. It contains only #i nci ude 
statements to include the other i nci ude files. 

• The second file, defines.h, contains all common #def i ne statements. Using a 
single, included file for a d ef i ne helps prevent the use of the same identifier 
being defined for two purposes. 

• T he next file, typedef.h, contains the program's typed ef statements. By placing 
all typedef statements in a single i nci ude file, all parts of the program can 
access them. There is no possibility of the same name being used for two 
different types if a single i nci ude fileisused. 

• Thevars.h file contains all thevariable definitions (and declarations). To see 
how a singlefile can contain both, see Listing 6.4, later in this chapter. 

• Thefinal file, prototyp.h, contains the function prototypes for each of the 
program's functions. Always keep prototypes in a singlefile, using the format 
shown in Listing 6.5, later in this chapter. 

Listing 6.1 shows themain i nci ude filefor a multisource file program. 
Listing 6.1. An exampleof a main i nci ude f i I e for a large project. 

# i nci ude "defines.h" 

# i nci ude "typedef.h" 

# i nci ude " v a r s . h " 

# i nci ude "prototyp.h" 



Listing 6.2 showsthedefines.h file. You should document each #def i ne'suseas 
shown in this example. 

L isti ng 6. 2. An exampleof thedefines.h include fi le. 

#i f ndef DEFI NES_ H 
#def i ne DEFI NES_ H 

continues 
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Listing 6.2. continued 



#d e f i ne 
#d e f i ne 
#d e f i ne 


MAX_ S 1 ZE 

USER 

MAXFONT 


123 /* 
" 1 AM 
50 / * 


Maximum size of array */ 
USER" /* The user's name */ 
Maximum number of fonts available * 


#i f ndef 
#d e f i ne 
tend i f / 


Ml N 

Ml N( a, b) 
* Ml N */ 


(((a) 


< (b)) ? (a) : (b)] 


#i f ndef 
#def i ne 
tend i f / 


MAX 

MAX( a , b) 
* MAX */ 


(((a) 


> (b)) ? (a) : (b)] 


#i f ndef 
#def i ne 
#endi f / 


TRUE 

TRUE 
* TRUE */ 


1 / * 


LOGI CAL TRUE */ 


#i f ndef 
#def i ne 
#endi f / 


FALSE 

FALSE 
* FALSE */ 


0 /* 


if not TRUE, must be FALSE */ 


#endi f / 


* DEFI NES H 


*/ 





Listing 6.3 shows the typedef.h file. As in other i nci ude files, you should 
document each t y p e d ef 's use as the example shows. 

Listing 6.3. An example of the typedef.h include file. 

#i f ndef TYPEDEF H 
#def i ne TYPEDEF H 

t y pedef struct 

{ 

char Font Li st [ MAXFONT] [ LFFACESI ZE] ; // MAXFONT is 50. L F_ FACES I ZE 

/ / is in wi ndows . h file. 

BYTE Char Set [ MAXFONT] ; // The font's character set 

BYTE Pi tchAndFami I y[ MAXFONT] ; // The font's pitch and 

/ / f a mi I y 

BYTE Vect or Or Rast er [ MAXFONT] ; // The font's type 
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BYTE 



Font Type[ MAXFONT] ; 



// RASTER_FONTTYPE, 

// DEVI CE_ F ONTTY PE , or 

// TRUETY P E_ F ONTTY P E 

/ / ( wi n d o ws . h ) 

// Index to the font size. 

// Index to the font. 



i nt 



n Si z e I nd ex ; 
n Fo n 1 1 nd ex ; 



i nt 



i nt 



nSi zeLi st [ MAX_ S I ZE] ; 



// List of font's sizes. 



} FONTSPECS; 



typedef FONTSPECS 



♦PFONTSPECS; 



typedef FONTSPECS NEAR * N P F ONTS P E CS ; 
typedef FONTSPECS FAR * L P F ONTS P ECS ; 



#endi f / * TYPEDEF H */ 



Thetypedef.hfileincludesnotonlyatypedef forthestructure, butalsot ypedef s 
for various pointers that may point to this structure. This inclusion makes it easy to 
create prototypes and to define the necessary structures and pointers later in the 
program. 

Listing 6.4, thevars.h file, includes all theglobal variables. It does not contain 
anyof thestaticvariablesbecausetheyareknown in onlythecurrentsourcefile. N otice 
the use of the defined identifier extern. This identifier is defined to theC keyword 
extern if thefilethat isincluding thevars.h fileisnot themain file. T hevariablesthen 
can beeitherdeclarations(doneonlyonce) or definitions (donein each file). For any 
initialized variable, you must check the extern identifier and process each one as 
necessary. As in theother include files, you should document each variable'suseasthe 
example shows. 

L i sti ng 6. 4. An exampleof thevars.h includefile. 

#ifndef VARS_H 
#def i ne VARS_H 

#ifndef EXTERN 

tdefine EXTERN / * NUL L , do variable declarations */ 



continues 
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Listing 6.4. continued 

#def i ne INI Tl ALI ZE_ EXTERN 
#e n d i f / * EXTERN */ 

EXTERN char s z Buf f er [ 2 5 7 ] ; /* Scratch buffer, contents undefined */ 
EXTERN char s z F i I e Na me [ 1 29 ] ; /* Input filename */ 

EXTERN i nt nErrorCount; /* How many errors so far? */ 

EXTERN i nt nErrorValue 

#i f defi ned( I Nl Tl ALI ZE EXTERN) /* Do the initialization */ 

= { NO_ ERROR} / * Initialized */ 
#e n d i f 



#i f defi ned ( I Nl Tl ALI ZEEXTERN) 
#undef I Nl Tl ALI ZE_ EXTERN 
#e n d i f 

#e n d i f / * VARS_H */ 



N oticethat vars.h uses the identifier extern and definesa new identifier called 
i ni ti ali ze extern. Whenever you aredeclaringavariablethatyou want to initialize, 
you can use this example to make sure that the variable is not declared twice. 

Listing 6.5, the prototyp.h file, includes all the function prototypes for the 
variousfunctionsin the program. Thisfileshould be the last of thegroup of included 
files becauseit usesthetypedef screated in typedef.h. As with theothen nci ude files, 
you should document each function's use and the file in which it is found, as the 
example shows. 

Listing 6.5. An example of the prototyp.h include file. 

#ifndef PR0T0TYP_H 
#def i ne PROTOTYPJ 

/* source file return name (para meters); */ 

/* ADDARRAY. C */ i nt Ar r a y Ad d ( L P ARRAY , LPARRAY); 

/* SUBARRAY.C */ i nt Ar r a y S u bt r a c t ( L PARRAY , LPARRAY); 
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/* UTILITY. C*/ void Er r or Message( LPSTR szSubStri ng, WORDwError, 

long I So me thing); 



#endi f / * PROTOYTPJ */ 



Theprototyp.h file has enough information for you to know each function's 
parameters, what the function returns, and where it is located (so that you can fix it 
when it breaks). 

By using thesei nci ude filesfor your project, you can beconfident that you have 
much of theproject under control. You will not haveduplicate external variables with 
thesamenameand different usage, and you won't havefunctionsdefined with oneset 
of parameters and declared with another. You must work at keeping thei nci ude files 
in order; however, in the long run, the result is worth the effort. 

External Variables 

Thischapter hasdiscussed using a set of standard i nci ude files. Thesefilesenableyou 
to control the way objects are defined in your programs, preventing duplicate 
identifiers with different meanings. Chapter 2, "Data Types, Constants, Variables, 
and Arrays," discussed variables, including external variables, and thischapter has 
discussed using a single i nci ude file to create both a definition and a declaration for 
an external variable. N ow let's look at a "real" program that shows how external 
variables work for you. 

The TWO FILE program, shown in Listings 6.6 through 6.14, is a simple 
program with twosourceC filesandafull set of i nci ude filesthatusesshared external 
(global) variables to share data. TWO FILE doesn't do much; however, it has the 
framework to enableyou to build a more meaningful application. 

L isting 6. 6. TWOFILE1.C. 

/* Program TWOFI LE, written 22 May 1 9 9 2 by Peter D. Hipson 

* A multisource file program. 

* This is the first source file for TWOFI LE. 

* / 

continues 
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Listing 6.6. continued 



/* This program assumes and uses Microsoft's extensions to C. 

* Readers with other compilers may need to change the program 

* to use the calls their compiler supplies to perform the 

* s a me functions. 

*/ 

#def i ne EXTERN extern 

finclude "twofile.h" /* TWOFILE's include has all other #includes. */ 



i n t ma i n ( 

i nt a r g c , 
char * a r g v [ ] , 
char * e n v p [ ] 
) 



{ 

char *pszTemp; 

char s z Bu f f e r [ 1 2 9 ] ; /* Temporary work buffer. */ 

char szProgram[ 30] ; 

char s z I n p u t F i I e [ 1 3 2 ] ; /* Make large enough for your OS. */ 

char s z Ou t p u t F i I e [ 1 3 2 ] ; /* Make large enough for your OS. */ 



/* strings for spl i tpat h( ) (which parses a file name) */ 
char szDr i ve[ _MAX_DRI VE] ; 
char szDi r [ _MAX_DI R] ; 
char s z F n a me [ _ MAX_ F NAME ] ; 
char szExt [ _MAX_EXT] ; 



nt i ; 

nt j ; 

nt n Cu r r e n t Pa r a met e r = I NNAME; 

nt nTempWi dt h =0; 

n t n L i n e Wi d t h =80; 

nt njustification = LEFT; 



if ( a r gc <= 2 ) 

{ 

Gi ve He I p( argc, NULL); 
r et ur n( 16) ; 

} 
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_ s p I i t pat h( a r g v [ 0] , 
s z D r i v e , 
s z Di r , 
s z F n a me , 
szExt ) ; 

strncpy(szProgram, szFname, sizeof(szProgram) ■ 1); 

for (i = 1; a r g v [ i ] ; i+ + ) 

{ 

if (argv[i ][0] == ' / ' | | a r g v [ i ][0] =='■') 

{ /* You have an argument, convert to lowercase, and test. */ 
pszTemp = s t r I wr ( a r g v [ i ] ) ; 

for (j = l; j < ( i nt ) st r I en( pszTemp) ; j + + ) 



case ARGLEFT: 

njustifi cation = LEFT; 
break; 

case A R G _ R I GHT: 

nj ust i f i cat i on = Rl GHT; 
break; 

case ARGJ USTI FY: 

nj usti f i cati on = J USTI FY; 
break; 

case ARG SLASH: 
case ARG_ DAS H: 
break; 

default: 

Gi veHel p( BAD OPTI ON, &pszTemp[ j ] ) ; 
break; 



switch! 



pszTemp! j ] ) 



else 



continues 
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Listing 6.6. continued 



/* Either a filename or width. */ 
s wi t c h ( nCurrentParameter) 

{ 

case I NNAME: 

st r c py ( s z I n put F i I e, a r g v [ i ] ) ; 
nCur r ent Par amet er = OUT NAME ; 
break; 

case OUT NAME : 

st r c py ( s z Out put F i I e, a r g v [ i ] ) ; 
nCur r ent Par amet er = Wl DTH; 
break; 

case Wl DTH: 

ssca nf ( a r gv [ i ] , "%d " , &nTe mpWi dt h) ; 

i f ( nTempWi dt h < 20 | | nTempWi dt h > 128) 

{ 

Gi ve He I p( BAD_WI DTH, NULL); 

} 

else 

{ 

n L i n e Wi dt h = n T e mpWi d t h ; 

} 

nCur r ent Par amet er = L AS T _ T H I NG; 

break; 

default: 

Gi v e He I p ( BAD_ PARM, NULL); 
break; 

} 



} 

} 

if ( nCur r ent Par a met er < Wl DTH) 

{ / * Didn't get t wo file names I */ 

Gi veHel p( NAMEMI SSI NG r NULL); 

r et ur n( 16) ; 
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} 



p r i n t f ( " \ n " ) ; 
pri nt f ( 

" %s would read the file ' %s ' and write the file ' %s ' \ n \ n " , 
s z P r o g r a m, 
szl nputFi I e, 
szOut put Fi I e) ; 

s wi t c h ( n J us t i f i c a t i o n ) 

{ 

case LEFT: 

pri ntf("The lines would be %d characters long, left \ 
a I i g n e d \ n " , 
n L i n e Wi d t h ) ; 
break; 

case Rl GHT: 

pri ntf("The lines would be %d characters long, right \ 
a I i g n e d \ n " , 
n L i n e Wi d t h ) ; 
break; 

case j USTI FY: 

pri ntf("The lines would be %d characters long, justified\n 

n L i n e Wi d t h ) ; 
break; 

} 

/* In the final version of this program, the files next 

* are opened, and the input file is read into a buffer, 

* formatted according to what the user wants, and written 

* out to the output file. At the end, the files are closed, 

* and perhaps some statistical information can be presented 

* to the user . 
*/ 



return ( 0) 
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Listing 6.7 is TWO FILE2.C, the second source file. It contains the help 
function. 

Listing 6.7. TWOFILE2.C. 

/* Program TWOFI LE, written 22 May 1 99 2 by Peter D. Hipson 

* A mu I t i source file program. 

* This is the second source file for TWOFILE: TWOFILE2.C. 

*/ 

/* This program assumes and uses Microsoft's extensions to C. 

* Readers with other compilers may need to change the program 

* to use the calls their compiler supplies to perform the 

* s a me functions. 

*/ 

tinclude "twofile.h" // TWOFI LE's include has all other # i n c I u d e s . 



void Gi v e He I p( 
i nt n Level , 
char * ps I t em) 



{ 



p r i n t f ( " \ n " ) ; 



s wi t c h ( n L e v e I ) 

{ 

case NOI NNAME: 

case NOOUTNAME: // Not enough parameters! 
pr i ntf ( 

'FORMAT [-r|-l|-j] inputfile outputfile width\n" 
where \ n " 

Options - -r (or / r ) to right align \n" 

- I (or / 1 ) to left align \ n " 

- j (or / j ) to j u s t i f y \ n " 

" \ n " 

inputfile ■ is the input file n a me \ n " 
outputfile - is the output file name \ n" 

" \ n " 

width is the desired output width (20 to 12 8) \ n " 
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(default is 80 c h a r a c t e r s ) . \ n " 

" \ n " 

Note: lines are concatenated, paragraph breaks a r e \ n " 
signaled with a blank I i n e \ n \ n " ) ; 

break; 

case BAD_WI DTH: 
p r i n t f ( 

"The width parameter must be between 20 and 12 8! \n" 
"the wi dt h is i g nor ed \ n " ) ; 
break; 

case BAD_ PARM: 

printf(" Excessive parameters have been entered\n"); 

/ * Force a display of full help! */ 

Gi veHel p( NOI NNAME, NULL); 
break; 

case BAD_ OPT I ON: 

p r i n t f ( " ' %c ' is an invalid option! (Use only - I , - r or \ 
■ i ) \ n " , 
* ps I t em) ; 

break; 

case NAME_ Ml SSI NG: 

printf("One or both of the required file names is \ 
mi s s i n g ! \ n " ) ; 

/ * Force a display of full help! */ 

Gi veHel p( NOI NNAME, NULL); 
break; 

default: 
p r i n t f ( 

"An unspecified error occured! FORMAT has ended! \ n " 
) ; 

continues 
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Listing 6.7. continued 

exit( 16) 
break; 

} 

} 



Listing 6.8 isTWOFILE.H , the main i nci ude filefor TWO FILE. 



Listing 6.8. TWOFILE.H. 

/* Program TWOFI LE, written 22 May 1 99 2 by Peter D. Hipson 

* A mu I t i source file program's main include file. 

* This is TWOFI LE' s include file. 

*/ 



/* This program assumes and uses Microsoft's extensions to C. 

* Readers with other compilers may need to change the program 

* to use the calls their compiler supplies to perform the 

* s a me functions. 

*/ 



/* First include the C language's include files: */ 

#i n c I ude <stdio.h> // Make includes first part of file 

#i n c I ude <string.h> // For string functions. 

#i n c I ude <stdlib.h> // Standard include items. 

#i n c I ude <process.h> // For exit(), etc. 

/ * Next , include TWOFI LE' s include files */ 



#i n c I ude " def i n e . h " 

#i n c I ude "typedef. h" 

#i n c I ude " v a r s . h " 

#i n c I ude "prototyp. h" 



/* End of this include file; put nothing but # i n c I ude statements 
* in this header! 

*/ 
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Listing6.9isD EFI N E.H , theidentifier identification i nci ude fileforTWO FILE. 
L isting 6.9. DEFINE. H. 

/* Program TWOFI LE, written 22 May 1 9 9 2 by Peter D. Hipson 

* A mu I t i source file program's tdefine include file. 

* This is TWOFI LE' s DEFI NE. H include file. 

*/ 

/* This program assumes and uses Microsoft's extensions to C. 

* Readers with other compilers may need to change the program 

* to use the calls their compiler supplies to perform the 

* s a me functions. 

*/ 



#def 


n e 


LEFT 1 




#def 


ne 


RIGHT 2 




#def 


ne 


j USTI FY 3 




#def 


ne 


1 NNAME 1 




#def 


ne 


OUTNAME 2 




#def 


n e 


Wl DTH 3 




#def 


ne 


L AS T_ T H 1 NG 4 




#def 


n e 


ARG_ LEFT 


1 ' 


#def 


ne 


ARG_ Rl GHT 


r ' 


#def 


ne 


ARGJ USTI FY ' 


j ' 


#def 


n e 


ARG_ SLASH 


/ ' 


#def 


ne 


ARG_ DAS H 




#def 


n e 


NOI NNAME 


1 


#def 


ne 


NOOUTNAME 


2 


#def 


ne 


BAD_ Wl DTH 


3 


#def 


n e 


BAD_ PARM 


4 


#def 


ne 


BAD_ OPT 1 ON 


5 


#def 


ne 


NAME Ml SSI NG 


6 



Listing 6.10 is TYPED EF.H, the identifier identification include file for 
TWO Fl LE. 
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Listing 6.10. TYPEDEF.H. 

/* Program TWOFI LE, written 22 May 1 99 2 by Peter D. Hipson */ 

* A mu I t i source file program's #d e f i n e include file. 
/* This is TWOFILE's TYPEDEF.H include file. */ 

/* This program assumes and uses Microsoft's extensions to C. 

* Readers with other compilers may need to change the program 

* to use the calls their compiler supplies to perform the 

* s a me functions. 

*/ 

/* This program uses no typedefs. */ 



Listing 6.11 isVARS.H , theexternal variables i nci ude filefor TW 0 F I LE . 
Listing 6.11. VARS.H. 

/* Pr ogr am TWOFI LE, written 22 May 1 99 2 by Peter D. Hipson */ 

* A multisource file program's external variables include file. 
/ * This is TWOFI LE' s VARS. H include file. */ 

/* This program assumes and uses Microsoft's extensions to C. 

* Readers with other compilers may need to change the program 

* to use the calls their compiler supplies to perform the 

* s a me functions. 

*/ 

/* This program uses no external variables. */ 



Listing 6.12 is PROTOTYP.H, the function prototypes' include filefor 
TWO Fl LE. 

Listing 6.12. PROTOTYP.H. 

/* Pr ogr am TWOFI LE, written 22 May 1 99 2 by Peter D. Hipson 

* A multisource file program's prototypes' include file. 

* This is TWOFILE's PROTOTYP.H include file. 

*/ 
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/* This program assumes and uses Microsoft's extensions to C. 

* Readers with other compilers may need to change the program 

* to use the calls their compiler supplies to perform the 

* s a me functions. 

*/ 



/* T WO F I LEI. C */ int ma i n ( i n t argc, char * a r g v [ ] , char * e n v p [ ] ) ; 
/* TWOFILE1.C */ void Gi veHel p( i nt nLevel, char * p s I tern) ; 



For a simple project that has only one source file, having five i nci ude files may 
seem like overkill. Perhapsitis, but for larger projects (with two ormoresourcefiles), 
it isn't long before you thank yourself for the organization these files offer. 

One of the keys to success is organization. Another is planning. Plan your 
program, and be sure it is organized. D isarray and chaos have no place in program- 
ming. Let's look at how you can keep your compiler output files better organized. 

Using an Object Library Manager 

W hen a large program is created with many source files, the process of creating the 
program is called building. This process consists of the following steps (refer to Fig- 
ure6.1): 

1. Compile each of the source files. The compiler's output usually is referred to as 
an object module and often has an .obj extension. 

2. Combine all the object modules the compiler has produced with theC 
language's libraries to create an executable program. 

3. In this optional step, you create symbol files that your debugger uses. Because 
each debugger is different, program creation is not discussed here. 

Everything's 0 K so far, but problems lurk. First, if your program is large, the 
linker's command-line input can get huge, even if the linker is driven by a file 
containing the necessary filenames. I have seen linker command lines that are several 
hundred lines long, but they're not pretty. 
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You can have a group of object modules in which your project isn't a program, 
but is just a collection of functions that perform a specific purpose and that (usually) 
isused with morethan one program. The various C library functions are an example. 

Grouping a number of functions together is called creating a library. Utility 
programs (supplied with your compiler and usually called LIB) perform various tasks 
with libraries. Let's look at M icrosoft's LIB utility. This program enables you to 
maintain your object code libraries and performs the following functions: 

• Adds an object moduleto the library 

• Deletes an existing object modulefrom the library 

• Replaces an existing object module in the library by performing a delete 
followed by an add 

• Extracts an object modulefrom the library 

• M aps a library and provides a listing of the library's contents, the sizes of the 
library's members, and the member's entry points and other external names 

In all cases, if the library doesn't exist, you have the option of creating it. An 
empty library can exist; however, it doesn't have much value. When M icrosoft's LIB 
program runs, it creates a backup copy of thelibraryand enablesyou to recover easily 
from errors. 

You can group functions in an object library by what they do. Thiscapabilityis 
handy because you can, for example, create a library of functionsthat read database 
files and a library of special math functions and keep them separate. 

Using MAKE Files 

Suppose that you have a program that consists of 35 source files. As you are editing 
them, you noteon paper which onesyou havechanged sothatyou can recompilethem. 
H ow long before you forget to compile one of the changed source files, and what are 
the effects? T he answer is "not long and the problems are difficult to find." 

Now suppose that you compiletheentire program every time. H ow long until 
you finish your program, and do you have any friends when you finish? The answer 
is "forever, and your friends have left you long ago." 
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T here has to be a better way— that's why we have computers. M any program- 
mers arefaced with thedilemma of whether it isfaster to do it by hand or to figureout 
howtomakethecomputerdoit. In thiscase, it'salwayspreferabletoletthecomputer 
do the work. This is where M AKE (also known by other names, such as N M AKE) 
comes in handy. 

TheM AKE utility has one purpose: It looks at the date on which onefilewas 
created or last modified and comparesittothedateof another file. If thefirstfileisolder 
than the second, the MAKE performs some specified action, such as compiling, 
linking, or another command that can be called from the command prompt. 

Someof themoreadvanced compilershavea utility that createstheM AK E files 
for you. If your compiler hasone, useit. (Creating a MAKE fileby hand involvessome 
work, but it can be done.) Listing 6.13 is a simple MAKE file that compiles 
TWOFILE, the example program discussed earlier. 

Listing 6.13. TWOFILE.MAK, a MAKE file to compileTWOFI LE . 

includes = twofile.h define, h typedef.h vars.h prototyp. h 

t wof i I e 1 . o bj : t wof i I e 1 . c $ ( i n c I u d e s ) 

c I - c - u - as - gs w - os - z pe t wof i I el . c 

t wof i I e 2 . o bj : t wo f i I e 2 . c {(includes) 

c I - c - u - as - gs w - os - z pe t wof i I el . c 

twofile.exe: twofilel.obj twofi I e2. obj 
link clockdat; 



In Listing 6.13, thevariablei nci udes isdefined first (yes, MAKE has variables). 
It contains thefollowing string: 

twofile.h define, h typedef.h vars.h prototyp. h 

Youusethistechniquetoreferencethei nci ude filesin aM AKE filetosavetyping 
and makeit easy to updatethelist (if you need to add a new include filelater). A defined 
variable in a MAKE file can be referenced by enclosing it within parentheses and 
preceding the opening parenthesis with a dollar sign. If the variable is undefined, the 
result isa blank, and no error isgenerated. T hiscapability can comein handy because 
you can define variables on the MAKE command line to change compiler options, 
linker options, or almost anything else. 
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Not listing the i nci ude file prototyp.h in the MAKE file is not uncommon; 
however, I recommend that you refer enceeveryfilethatmakesup part of your project. 

Thefollowing line is called a dependency line: 

t wof i I e 1 . o bj : t wo f i I el. c $ ( i n c I u d es ) 

It tells M AKE that the fi le twofi lel.obj might change if any of the files following the 
: change. In thiscase, twofilel.obj maychangeif twofile.coranyof the i nci ude files 
changes. T here is a limit to what M AK E can see: 1 1 looks only at thefiles' timestamp. 
If twofilel.c or any of thei nci ude files is newer than twofilel.obj, the dependency is 
true, and MAKE performs whatever commands immediately follow the dependency 
line: 

c I - c - u - as - gs w - o s - z pe t wof i I el . c 

These commands, however, must start in a column other than the first one (I 
recommend that you indent them four spaces). 

In a MAKE file, the # character is the comment delimiter. If you want to 
comment your M AKE file(l recommend it), simply use the comment delimiter (see 
Listing 6.14). M AKE continuesto process theM AKE fileuntil oneof thecommands 
returns a nonzero return code or until the MAKE file ends. Rarely do you want to 
continue to run MAKE after an error has been detected. Listing 6.13 is a simple 
MAKE file. Listing 6.14 isamoreadvanced M AKE file, again written forTW 0 FI LE. 

Listing 6. 14. TWOFI LE, an advanced MAKE filefor theTWOFILE 
program. 

##### Modul e Macro ##### 

NAME = t wof i I e 

SRCS = twofilel.c twofile2.c 
OBJ S 

##### C7 Macro (if you have Microsoft C-7) ##### 

C7 = 1 

##### Library Macros (if programming under Windows) ##### 

LIBS = libw mlibcew 

MOD = -AM 

##### I nci ude Macro ##### 

INCLS = $ ( NAME) . h define, h typedef.h vars.h prototyp.h 
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#### DEBUG Def i n ed ##### 
DEBUG = 1 

##### Bui Id Opti on Macros ##### 

! i f $( DEBUG) 

DDEF = - DDEBUG 

CLOPT = - Zi d - Od 

MOPT = - Zi 

LOPT = / CO / LI / MAP 

I e I s e 

DDEF 

CLOPT = - Os 

LOPT 

I end i f 

##### General Macro ##### 
DEF 

##### Tool Macros ##### 

ASM = masm - Mx $( MOPT) $( DDEF) $( DEF) 

CC = cl -nologo -c $(MOD) -G2sw -Zp - W3 $ ( CLOPT) $ ( DDEF ) $ ( DEF) 
LINK = link / NOD / NOE $ ( LOPT) 
RC = rc $( DDEF) $( DEF) 
HC = he 

##### Inference Rules ##### 
. c . o bj : 

$(CC) $*.c 

. asm. obj : 

$(ASM) $*.asm; 

. r c . res: 

$ ( RC) - r $*. rc 

##### Mai n ( def aul t) Target ##### 
goal : $( NAME) . exe 



##### Dependents For Goal and Command Lines ##### 
$( NAME) .exe: $(SRCS:.c=.obj) 
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Listing 6.14. continued 

$( LI NK) @<< 

$( SRCS: . c=. o b j ) $ ( OBJ S ) , 
$( NAME) . exe, 
$( NAME) .map, 
$(LI BS), 
$ ( NAME ) . def 

<< 

!if $ ( DEBUG) 
! i f ! $( C7) 

cvpack - p $( NAME), exe 
! e n d i f 

ma ps y m $ ( NAME ) . ma p 
! e n d i f 

##### Dependents ##### 
$( SRCS: . c=. Obj ) : $ ( I NCLS) 

##### Clean Di rectory ##### 
c I ea n : 

- del *. obj 

- del *. exe 



Thisexampleof aM AKEfiledoeslittlemorethan thefirst, simpler example, but 
it doeshavethecapabilitytoquicklyadd new source(.C) files, to switch between debug 
mode and a final production version, and to handle M icrosoft C 7's differences. 

In all, MAKE isoneof the most important tools you have to help you produce 
your program. W ithout it, you have to do most of the work in creating your program, 
such as calling the compiler and linker. 



Summary 

This chapter described programs made up of more than one source file and how to 
manage larger, multisourcefile proj ects. 

• Thecompiler is used to compileeach source file. 
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• When all the source files are compiled (successfully), they are combined, using 
a linker, to produce the final executable program. 

• T he #i n c i u d e statement causes the C compiler to read in the named file as 
though it were part of the original file. 

• When the included file ends, the compiler continues with the original file. 

• External variables, identified with theexter n keyword, can be used to share 
information between functions, even when thefunctions reside in different 
source files. 

• Theobject library utility (LIB) isused to maintain library files. 

• MAKE files are used to help automate the process of creating a large program 
that has more than one source file. 



187 



c 

Part II 

c 



Managing Data in C 



Structures 



A computer language would be ineffective if it did not offer a way to create complex 
dataobjects. C structuresareobjectsth at contain morethan oneitem. A structureoften 
contains data objects grouped according to their usage, but a structure can contain 
u n rd ated data obj ects as wd I . 

Using the struct Keyword 

You usethestr uct keyword to define a structure. A structure definition consists of 
several parts, as the following shows: 

struct t a g _ n a me { 

type member _ name; 
type member _ name; 
type member_name; 
} str uct ur e_name = 

{ i n i ti al i z e r _ v a I ues}; 
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Although theformattingisuptotheprogrammer, I suggest that you usethepreceding 
format for easy readability. 

Thefirst line contains thes t r uct keyword, then theoptional tag name: 

struct t a g _ n a me { 

T he t a g n a me can be u sed to create a copy of th e stru ctu re ( as sh own i n ST R U C T 4. C , 
on e of the exam pi e program s i n th i s ch apter) . A n open i ng brace f ol I ows th e t a g n a me 
(or thes t r u c t keyword, if thet a g n a me isnot used). T his bracesignalsto thecompiler 
that the next lines are member definitions Each member definition consists of a 
variabletypeandanameThememberscan beany val id variabletype, including arrays, 
structures, and unions, as follows: 

type me mb e r _ n a me ; 
type member _ name; 
type member _ name; 

Followingthelastmembernameisaclosingbraceandtheoptionalstr uct ure name, 
as foil ows: 

} s t r u c t u r e_ n a me = 

When using thes t r uct ur en a me and thet ag_ name, you can choose any of the 
following: 

• If astructurename is not specified and a t a g_ na me is specified, the structure is 
being defined but not declared. 

• Ifastructure name is specified and a t ag_ name is not specified, the structure is 
being declared but not defined. 

• If astructurename and a t a g_ na me are provided, the structure is being both 
defined and declared. 

• If neither astr uct ure_name noratagname is provided, a compile-time error 
will result. 

If you want to initialize thestructure, you must haveast r uct ur e name because 
it signals thecompiler that this is a declaration. Thest r uct ur ename is also necessary 
if you want to refer to the structure. 

After thest r uct ur e name are optional initializers: 

{i ni t i al i zer val ues>; 
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Thefollowing is a simple structure: 



struct 



char 
i nt 



szSayi ng[ 129] ; 
nLengt h; 



} MySayi ng; 

This structure definition provides a data object that can be referenced with a single 
name, MySayi ng. Each member of MySayi ng provides different information. 

Structures offer usa number of important advantages, including thefollowing: 

You can refer to the entire data object using a single name. 

You can use the structure name as a parameter to a function. For example, 
you could pass the address and the length of the structure name to read o 
to read the structure's contents from a disk file. 

Structures can be assigned directly. You cannot assign strings (you must use 
the s t r c p y ( ) library function), but you can assign two structures simply by 
using an assignment statement. 

A function can return a structure. 

Asimpleprogramthatallocatesand initializesastructureisshown in Listing 7.1. 



/* STRUCTl, written 1 9 9 2 by Peter D. Hipson 
* This is a simple structure program. 

*/ 

tinclude < s t d i o . h > // Make includes first part of file 
#include <string.h> // For string functions 

int main(void); // Define ma i n ( ) and the fact that this 



Listing 7.1. STRUCTl. C. 



// program doesn't use any passed parameters 



int ma i n ( ) 



continues 
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Listing 7.1. continued 



nt 



struct 
{ 

char s z Sa y i ng [ 129] ; 
i nt nLengt h; 

} MySayi ng = 

{"Firestone's Law of Forecasting:", 

s t r I en ( My Say i ng . s z Sa y i ng ) } ; 

p r i n t f ( " s i z eof ( MYSay i ng) = %d\n", s i z eo f ( My Sa y i ng ) ) 

pr i nt f (" MySayi ng %p %3d ' %s' \ n" , 
& My S a yi ng. szSayi ng, 
MySayi ng. nLengt h , 
MySayi ng. szSayi ng) ; 

p r i n t f ( " \ n \ n " ) ; 

return ( 0) ; 



In STRUCT1, you can see the definition of the My sa y i ng structure. This 
structure has two members: a character string (with a length of 129) called s z s a y i n g 
and an integer variablecalled n l e n g t h . T hestructureisinitialized with a lineof text and 
a number. T heprogram then initializes then Length member to thelength of thestring 
in thes z sa y i n g member. (U sing a function call to initializea data object is permitted 
but uncommon.) 

N oticehow the program refers to each member in the structure. T he shorthand 
for a structure reference is the structure name followed by a period and the member 
name: 

structure, me mb e r 

If the member is also a structure (more on this later), the member name is 
followed by a period and its member name: 

structure, me mb e r s t r u c t u r e . me mb e r 
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Arrays of Structures 



As mentioned, an array can consist of any data type. I n this section, you look at an 
exampleof a program that usesan array of types t r u c t . Listing 7.2, ST RU CT 2, creates 
a structure, makes it an array, and initializes it. 



Some compilers will not compile Listing 7.2 correctly, even 



/* ST RUCT 2 , written 1 9 9 2 by Peter D. Hipson 
* This program creates an array of type struct 

*/ 

# i n c I u d e <stdio.h> // Make includes first part of file 
tinclude <string.h> // For string functions 

int main(void); // Define ma i n ( ) and the fact that this 




though it is legitimate AN SI code. 



L isting 7.2. STRUCT2.C. 



// program doesn't use any passed parameters 



int ma i n ( ) 



i nt 



struct 



char s z Sa y i ng [ 12 9] ; 
int nLengt h; 



} MySayi ng[ ] = { 

"Firestone's Law of Forecasting:", 0, 



continues 
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Listing 7.2. continued 

Chicken Little has to be right only once.", 0, 

"", 0, 
"", 0, 

" Ma n I y ' s Ma x i m: " , 0, 

Logic is a systematic me t hod of coming to", 0 , 
the wrong conclusion with confidence.", 0, 

"", 0, 
"", 0, 

" Moe r ' s truism:", 0, 

The trouble with most jobs is the job holder's", 0, 
resemblance to being one of a sled dog team. No one", 0, 
gets a change of scenery except the lead dog.", 0, 

"", 0, 
"", 0, 

"Cannon's Co mme n t : " , 0 , 

If you tell the boss you were late for work because you", 0, 
had a flat tire, the next morning you will have a flat tire.", 

0, 

}; 

for ( i =0; 

i < ( si zeof ( MySayi ng) / s i z e of ( My Sa y i n g [ 0 ] ) ) ; 
i ++) 

{ 

My Sa y i n g [ i ] . n L e n g t h = s t r I e n ( My Sa y i n g [ i ] . s z Say i n g ) ; 



p r i n t f ( " s i z eof ( My Say i ng) = %d\n", s i z eo f ( My Sa y i ng ) ) ; 

pri ntf ( " Number of e I e me n t s = %d \ n " , 

( si zeof ( MySayi ng) / s i z eof ( My Sa y i ng [ 0 ] ) ) ) ; 

for ( i =0; 

i < ( si zeof ( MySayi ng) / s i z e of ( My Sa y i n g [ 0 ] ) ) ; 
i ++) 

{ 

pr i ntf ( "MySayi ng[ %2d] %p %3d ' %s ' \ n", 
i , 

& My S a y i ng[ i ] . szSayi ng, 
MySayi ng[i ]. nLength, 
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MySayi ng [ i ] . s z Sa y i n g ) ; 



p r i n t f ( " \ n \ n " ) ; 
return ( 0) ; 

} 



Let's look at how the structure is declared. In the first few lines, the structure 
members and the structure's name are established: 



} MySayi n g [ ] = { 

I n the last line of this code fragment, brackets indicate that an array is being defined. 
(A nonstructure array is declared in this way also.) Following arethearray brackets, 
which do not have a size. This tells the compiler to compute the number of elements 
in MySayi ng from the initializers. 

I havenot specified thenumber of elements; instead, thecompiler computesthis 
number. Whilethe program isexecuting, it calculates the number of members using 
a simple formula: 

nNumber Of Member s = (sizeof(MySaying) / s i z e of ( My Say i n g [ 0 ] ) ) 

Thetotal size of the structure is divided by the size of the first member. (Remember 
that all members must be the same size.) T his gives us the number of elements in the 
structure array. Computing thenumber of dementsin this way is handy. If you want 
to change the initializers to add a new saying, for example, you won't have to change 
the program. 

You can write a macro to compute the number of elements as follows: 

tdefine NUMBER_ELEMENTS( array) ( s i z eof ( a r r a y ) / s i z eof ( a r r a y [ 0 ] ) ) 

If you givethismacrothenameof an array (of any type), it returnsthe number 
of dementsin thearray. An exampleisshown in Listing 7.3, theST RU CT A program. 
Themacro makes it easy to use loopsto index an array whose number of dementshas 
been determined by the initializers (or by any other means). 



struct 



char 



szSayi ng[ 129] ; 
nLengt h; 



i nt 
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Listing 7.3. STRUCTA.C. 

/* STRUCTA, written 1 9 9 2 by Peter D. Hipson 

* A program showing a macro to determine the 

* number of elements in an array. 

*/ 

#i n c I u d e < s t d i o . h > // Make includes first part of file 
tinclude <string.h> // For string functions 

/* The NUMBER_ELEMENTS( array) macro returns the number of 

* elements found in array. Array can be any array, including 

* an array of type struct. 

*/ 

tdefine NUMBER_ELEMENTS( array) ( s i z eof ( a r r a y ) / s i z eof ( a r r a y [ 0 ] ) ) 

int main(void); // define ma i n ( ) , and the fact that this program doesn't 
/ / use any passed pa r a met er s . 

int ma i n ( ) 

{ 

int i ; 

struct 
{ 

char s z Sa y i ng [ 129] ; 
int nLengt h; 

} MySayi ng[ ] = { 

"Firestone's Law of Forecasting:", 0, 

Chicken Little has to be right only once.", 0, 
"", 0, 
"", 0, 

" Ma n I y ' s Ma x i m: " , 0, 

Logic is a systematic me t h o d of coming to", 0 , 
the wrong conclusion with confidence.", 0, 

"", 0, 
"", 0, 

" Moe r ' s truism:", 0, 
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The trouble with most jobs is the job holder's", 0, 
resemblance to being one of a sled dog team. No one", 0, 
gets a change of scenery except the lead dog.", 0, 

"", 0, 
"", 0, 

"Cannon's Co mme n t : " , 0 , 

If you tell the boss you were late for work because you", 0, 
had a flat tire, the next morning you will have a flat tire.", 

0, 

}; 

for (i =0; i < NUMBER_ ELEMENTS) MySayi ng) ; i ++) 

{ 

My Sa y i n g [ i ] . n L e n g t h = s t r I e n ( My Sa y i n g [ i ] . s z Sa y i n g ) ; 

} 

printf( /* String literal concatenation makes formatting lists easy 



"Number of MySayi ng elements = %d\n" 

"si zeof( MySayi ng[0] . szSayi ng) = %d \ n " , 

si zeof( MySayi ng) , 

N U MB E R_ E L E ME NTS ( MySayi ng) , 

NUMBER, ELEMENTS! MySayi ng[ 0] . szSayi ng) ) ; 

for ( i =0; 

i < NUMBER_ELEMENTS( MySayi ng) ; 
i + + ) 

{ 

pr i ntf ( " MySayi ng[ %2d] %p %3d ' %s ' \ n", 



*/ 

"si z eof ( My Sa y i n g ) 



= %d\ n" 



& MySayi ng[ i ]. szSayi ng, 
MySayi ng[ i ] . nLength, 
MySayi ng [ i ] . s z Sa y i n g ) ; 



p r i n t f ( " \ n \ n " ) ; 



return ( 0) ; 
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As Listing 7.3 shows, creating arrays of structures issimpleand straightforward. 
Under ANSI C, you can initialize an auto structure as both a singular entity and an 
array, which makes it easier to use structures. 

Listing 7.3 has someproblems, however. Notethesizeofthestructurewhen you 
run the program. Itishuge! Becausethesizeof thelargest initializing string cannot be 
determined easily, I madetheszst ring member large enough for all (or almost all) 
strings, 129 characters.! hecompileraddsabyteto pad thislength to a word boundary, 
makingthelength 130. Thetotal length ofthestructure— includingtheinteger length 
member, nLength — is 132 bytes. There are 18 membersin the array of structures. 
When I compiled and executed the program, thetotal length was 2376 bytes. Perhaps 
there is a better way. 

Structures of Arrays 

If you can makean array from astructure, can astructurecontain an array?Of course! 
The process of defining an array in a structure was demonstrated in Listing 7.3, in 
which the s z st r i n g variable is a string variable, and string variables are made up of 
arrays of type char. 

An advanced version of STRUCT A isshown in STRUCT3.C, Listing 7.4. This 
program stores pointers to a ragged-right array of character initializers. Because the 
program doesnot allocateadditional space, thisversion isuseful when thesaved strings 
will not be modified. If you have to modify thesaved strings, STRUCT A is a better 
choice. 

Listing 7.4. STRUCT3.C. 

/* STRUCT3, written 1 9 9 2 by Peter D. Hipson 
* A structure containing an array (or two). 

*/ 

tinclude < s t d i o . h > // Make includes first part of file 
#i n c I u d e <string.h> // For string functions 

#def i ne N U MB E R_ E L E ME NT S 35 

int main(void); // define ma i n ( ) , and the fact that this program doesn't 
/ / use any passed pa r a met er s . 
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i n t ma i n ( ) 
{ 

i nt i ; 

struct 
{ 

char * s z S a y i ng[ NUMB E R_ E L E ME NTS ] ; 

i nt nLengt h [ NUMBER_ ELEMENTS] ; 

} Our Say i ng = { 

"Firestone's Law of Forecasting:", 

Chicken Little has to be right only once.", 

" Ma n I y' s Max i m: " , 

Logic is a s y s t e ma t i c me t hod of coming to", 
the wrong conclusion with confidence.", 

" Moe r ' s truism:", 

The trouble with most jobs is the job holder's", 
resemblance to being one of a sled dog team. No one", 
gets a change of scenery except the lead dog.", 



"Cannon's Co mme n t : " , 

If you tell the boss you were late for work because you", 

had a flat tire, the next morning you will have a flat tire.", 

NULL /* Flag to mark the last saying */ 

}; 

for ( i =0; OurSayi n g . s z Sa y i n g [ i ] ; i + + ) 

{ 

Our Sayi ng. nLengt h[ i ] = s t r I e n ( Ou r Sa y i n g . s z S a y i n g [ i ] ) ; 

} 

p r i n t f ( " s i z e o f ( 0 u r S a y i n g ) = %d \ n " , s i z e o f ( 0 u r S a y i n g ) ) ; 
for ( i =0; OurSayi n g . s z Sa y i n g [ i ] ; i + + ) 

continues 
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Listing 7.4. continued 

{ 

pr i nt f ( " Our Say i ng %p %3d ' %s' \ n" , 
&Ou r Say i ng . s z Say i ng [ i ] , 
OurSayi ng. nLength[ i ], 
OurSayi ng. szSayi ng[ i ] ) ; 

} 

p r i n t f ( " \ n \ n " ) ; 
return ( 0) ; 

} 



Becausel donotwanttocountbyhandhowmanystringswillbeusedtoinitialize 
the structure and cannot (in this context) letthecompilercomputethenumber, I have 
a problem. I must specify the number explicitly. I chose a value of 35 (the identifier 
iscalled numberelements) becausel knew that there would notbemorethan 35 lines 
of sayings. 

Although the number of elements is fixed at 35, all of them are not initialized. 
T herefore, theprogram needsa way to know when theend of thelist has been reached. 
Thisisaccomplished by adding a pointer with theNun valueasthelast initializer. The 
program can test for the end of the array using a conditional test, such as 

for (i = 0; OurSayi ng. szSayi ng[ i ] ; i ++) 

BecauseAN SI C hasdefined null asapointerthatisneverused,and becausethevalue 
of null is usually zero when programming under DOS, this test always works. 

If you areunwillingtoassumethatNULL is always defined as a zero value, the test 
could be rewritten as 

for (i = 0; OurSayi ng. szSayi ng[ i ] != NULL; i + + ) 

Thisconditional comparison of the pointer and null makes thetest more explicit. I 
did not test for a zero-length string because the blank lines between sayings have a 
length of zero. 
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Itiscommon to have members of astructurebestructures themselves. Themaximum 
level of nesting is 15 according to the AN SI C standard. (You areunlikeiy to reach this 
limit.) 

Listing 7.5, STRUCT4, has nested structure definitions. This program (built 
f rom ST R U C T ) h as M u rphy's sayi n gs an d a f ew oth ers I h ave col I ected over th eyears. 

L isting 7.5. STRUCT4.C. 

/* STRUCT4, written 1 9 9 2 by Peter D. Hipson 
* A program wi th nested structures. 

*/ 

tinclude < s t d i o . h > // Make includes first part of file 
# i n c I u d e <string.h> // For string functions 

int main(void); // Define ma i n ( ) , and the fact that this program doesn't 



/ / use any passed pa r a met er s . 



int ma i n ( ) 



i nt 



i ; 



struct SAYI NG 



char 
i nt 



*szSayi n g [ 3 5] ; 
nLengt h[ 35] ; 



}; 



struct 



struct SAYI NG Mur phy; 
struct SAYI NG Peter; 



} Ou r Say i ng = { { 

"Firestone's Law of Forecasting:", 



continues 
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Listing 7.5. continued 



Chicken Little has to be right only once. 



Ma n I y ' s Ma x i m: " , 

Logic is a s y s t e ma t i c me t hod of coming to", 
the wrong conclusion with confidence.", 



Moe r ' s truism:", 
The trouble with most jobs is the job holder's", 
resemblance to being one of a sled dog team. No one" 
gets a change of scenery except the lead dog.", 



Cannon's Co mme n t : 

If you tell the boss you were late for work because you", 
had a flat tire, the next morning you will have a flat tire. 

NULL /* Flag to mark the last saying */ 

}, { 

Da v i d ' s rule:", 
Software should be as easy to use as a Coke machine.", 



Peter's Max i m: " , 
To be successful, you must work hard, but' 
Hard work doesn't guarantee success.", 



Teacher's truism:", 

Successful people learn.", 



Player's Co mme n t : " , 

If you don't play to win,", 

you don't win.", 
NULL /* Flag to mark the last saying */ 
}}; 



for (i = 0; Ou r Say i n g . Mu r phy . s z Say i n g [ i ] ; i ++) 
{ 
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OurSayi ng. Murphy. nLength[ i ] = 

st r I e n ( OurSayi ng. Murphy. szSayi n g [ i ] ); 

} 

pri ntf( "si zeof(OurSayi ng. Murphy) = %d\n", si zeof(OurSayi ng. Murphy) ); 

for (i = 0; OurSayi ng. Murphy. szSayi ng[ i ] ; i + + ) 

{ 

pri ntf("OurSayi ng. Murphy %p %3d '%s'\n", 
&Ou rSayi ng. Murphy. szSayi ng[ i ] , 
OurSayi ng. Murphy. nLengt h[ i ] , 
OurSayi ng. Murphy. szSayi ng[ i ] ) ; 

} 

p r i n t f ( " \ n \ n " ) ; 

for (i = 0; OurSayi ng. Peter . szSayi ng[ i ] ; i + + ) 

{ 

OurSayi ng. Peter. nLengt h [ i ] = strl e n ( Ou r S a y i ng. Peter. szSayi n g [ i ]) ; 

} 

pri ntf( "si zeof(OurSayi ng. Peter) = %d\n", s i z eof ( Ou r Sa y i n g . P et er ) ) ; 

for (i = 0; OurSayi ng. Peter. szSayi ng[ i ] ; i + + ) 

{ 

pri ntf( "OurSayi ng. Peter %p %3d '%s'\n", 
&Ou r Say i ng . Pet er . s z Say i ng [ i ] , 
Our Sayi ng. Pet er . nLengt h[ i ] , 
OurSayi ng. Peter. szSayi ng[ i ] ) ; 

} 

p r i n t f ( " \ n \ n " ) ; 
return ( 0) ; 



ST RU CT4 is the first program in this book that has used the structure tag. The 
definition of the structure is 

struct SAYI NG 

{ 
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char * s z S a y i ng[ 35] ; 

i n t n L e ng t h [ 3 5 ] ; 

}; 

I createa definition of a structure, but I do not declare the structure (that is, I do not 
allocate storage). I assign thenamesAYi ng totheoptional tag position. Thisnamecan 
be referred to in future declarations of structures of the same type. 

Next, I declare the structure, which has two members: Murphy and Peter .The 
structure is then initialized: 

struct 
{ 

struct SAYI NG Murphy; 
struct SAYI NG Peter; 
} OurSayi ng = {{...},{... }}; 

N otetheuseof initialization braces: theentireinitializer isenclosed with aset of braces, 
th en each of th e n ested stru ctu re's i n i ti al i zers i s en cl osed i n a set of braces. Bygrouping 
theinitializersintotwo blocks, these braces tell thecompiler which initializer goeswith 
which nested structure. 

Then the structure is accessed using the same syntax shown in the previous 
examples, except a name(either Murphy orpeter) is added to tdl thecompiler which 
member to use: 

for (i = 0; OurSayi ng. Murphy. szSayi ng[i ]; i + + ) 

{ 

OurSayi ng. Murphy, n L e n g t h [ i ] = strl en( OurSayi ng. Mur phy. szSayi n g [ i ] ) ; 

} 

A saying or length in the mu r phy part of the structure is accessed with 

Ou r Say i n g . Mu r phy . 

and a saying or length in the Peter part of the structure is accessed with 

OurSayi ng. Peter. 



Bit Fields in Structures 

I nascalardata object, thesmallest object that can beaddressed directly isusuallyabyte. 
In a structure, you can define data objects from 1 to 16 bits long. 
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Suppose your program contains a number of TRU E/FALSE variables grouped 
in a structure called status, as follows: 

struct { 



unsi gned 


nt 


b 


sVal i d; 


u n s i gned 


nt 


b 


s F u 1 1 5 i z e ; 


unsi gned 


nt 


b 


s Co 1 or; 


unsi gned 


nt 


b 


sOpen; 


unsi gned 


nt 


b 


s Sq u a r e; 


unsi gned 


nt 


b 


sSof t ; 


unsi gned 


nt 


b 


sLong; 


unsi gned 


nt 


b 


s Wi d e ; 


unsi gned 


nt 


b 


s Boxed ; 


unsi gned 


nt 


b 


s Wi n d o we d ; 



} Status; 

This structure requires 20 bytes of storage, which isalot of memory for saving 
afewTRU E/FALSE variables. It would be better to save each variable using only one 
bit. Perhaps you could use a single, bit-mapped variable (described in Chapter 5, 
"Decimal, Binary, H ex, and Octal"). Sometimes, however, your flags must keep the 
identity that a unique name offers. 

C offersthecapabilitytodefinethewidth of avariable, but only when thevariable 
isin astructurecalled abitfidd. For example, you could rewritethedefinition of st at us 
as follows: 

struct { 



unsi gned 


nt 


b 


sVal i d: 1; 


unsi gned 


nt 


b 


s F u 1 1 S i z e 


unsi gned 


nt 


b 


s Co 1 o r : 1 ; 


unsi gned 


nt 


b 


sOpen: 1; 


unsi gned 


nt 


b 


sSquar e: 1 


unsi gned 


nt 


b 


sSof t : 1; 


unsi gned 


nt 


b 


sLong: 1; 


unsi gned 


nt 


b 


s Wi d e : 1 ; 


unsi gned 


nt 


b 


sBoxed: 1; 


unsi gned 


nt 


b 


s Wi n d o we d 



} Status; 

The: i that appears after each variable's nametdlsthecompiler to allocateone 
bit to thevariable. Thus, the variable can hold only a 0 or a 1. This is exactly what is 
needed, however, because thevariablesareTRU E/FALSE variables. The structure is 
only two bytes long (onetenth thesize of the previous example). 
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A bitfield can hold morethan asinglebit. For example, it can hold a definition 
of a structure member, such as 

unsigned i nt nThreeBi ts: 3; 

In thisexample, nThreeBi ts can hold any valuefrom 0 to 7. 

Themost critical limitation to using bit fields is that you cannot determinethe 
addressof a bit field variable. I f you usethea d d r es s of operator, a compile-timeerror 
results. This means that you cannot pass a bit-field's address as a parameter to a 
function. 

W hen thecompiler stores bit fields, it packs them into storage without regard to 
alignment. Therefore, storage is used most efficiently when all your bit fields are 
grouped together in thestructure. You can force the compiler to pad thecurrent word 
so that the next bitfield startson a word boundary. To do so, specify a dummy bit field 
with a width of 0, for example: 

struct { 



unsi gned 


i nt 


bl sVal i d: 1; 


unsi gned 


i nt 


bl sFul 1 Si ze 


unsi gned 


i nt 


b R e s e r v ed 1 : 


unsi gned 


i nt 


bl s Box ed : 1 ; 


unsi gned 


i nt 


bl sWi n do wed 



} Status; 

ThebReservedi bit field tellsthe compiler to pad to thenext word boundary, 
which results in thebi s Boxed bitfield starting on a known boundary. This technique 
is useful when the compiler is packing structures and you need to know that the 
alignment is as optimal as possible. (Some computers access objects faster when the 
objects are aligned on word or double word boundaries.) 

U sing the typedef Keyword 

I think that thetypedet keyword is one of the best parts of the C language. It enables 
you to create any data type from simple variables, arrays, structures, or unions. 

Thetypedet keyword isused todefineatypeof variable, just asitsnameimplies. 
You can defineany type from any other type. A variable created with typedef can be 
used just like any other variable. Listing 7.6, CREATEDB.C, is a simple example of 
usingtypedet with structures. 
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L isting 7.6. CREATEDB.C. 

/* CREATEDB, written 1 9 9 2 by Peter D. Hipson 

* This program demonstrates typedef. The program 

* has minimal error checking; it will fail if 

* you enter a field value that is too long for 

* the structure member that holds the value. 

* Use with caution! 
*/ 



#i nc I u d e <s t r i n g . h > 

#i nc I ude <ct ype. h> 

#i nc I ude <st di o. h> 

#i nc I ude <pr oces s . h> 

# i n c I ude <s t d I i b . h > 



#def i ne C U S T 0 ME R_ R E C OR D 1 
#def i ne SUPPLI ER_ RECORD 2 

/* Define the structure for the customer database */ 
typedef struct _CUSTNAME { 



i nt 


n Rec o r d T y pe; 


/ 1 == C u s t o me r record 




char 


szName] 61] ; 


/ 60 chars for name; 1 for null at 


end 


char 


szAddr 1[ 61] ; 


/ 60 chars for address; 1 for null 


at end 


char 


s z Ad d r 2 [ 61] ; 


/ 60 chars for address; 1 for null 


at end 


char 


szCi t y [ 2 6 ] ; 


/ 25 characters for city; 1 for nu 


1 1 at end 


char 


szSt at e[ 3] ; 


/ 2-character state abbrev. plus null 


i nt 


nZi p; 


/ Use integer. Print as %5 . 5 d for 


leading 0 


i nt 


n Rec o r d N u mbe r ; 


/ Wh i c h record number? 




d o u b 1 e 


dSal esTot al ; 


/ Amount customer has purchased 




} CUSTNAME; 







typedef CUSTNAME near * NPCUSTNAME; 
typedef CUSTNAME * PCUSTNAME ; 

void ma i n ( ) 

continues 
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Listing 7.6. continued 



FILE 



* Da t a F i I e; 



CUST NAME 



C u s t o me r ; 



char 
char 



s z F i I e N a me [ 2 5 ] ; 
sz Buffer [129]; 



i nt 



i ; 



i nt 



n Res u I t ; 



double d S a I e s = 0.0; // Forces loading of floating-point support 
p r i n t f ( " Please enter customer database name: "); 
gets(szFileName); 

Data File = fopen(szFi I eName, "wb"); 
if ( DataFi I e == NULL) 



printf(" ERROR: File ' %s ' couldn't be opened. \n", szFileName); 



Cus t o mer . s z Na me [ 0] = 'A'; // To get past while() the first time 
i = 0; 

Customer. nRecordNumber = 0; 

while (strl en( Customer. szName) > 0) 



exi t ( 4) ; 



memset ( &C u s t omer , 0, si zeof ( CUSTNAME) ) ; 



pri ntf( "Enter the C u s t o me r ' s n a me : " ) 
get s ( Cus t o me r . s z Na me) ; 
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if ( strl en(Customer . szName) > 0) 

{ 

Customer. nRecordNumber = i; 

do 

{ 

pri ntf( "Enter 1 for c u s t o me r , 2 for supplier " ) ; 
get s ( s z Buf f e r ) ; 

sscanf ( szBuf f er , "%d", &C u s t o me r . n Re c o r d Ty pe ) ; 

} 

while (Customer. nRecordType != CUSTOMER_ RECORD && 
Customer. nRecordType != S UP P L I E R_ RE CORD) ; 



pri ntf("Enter address line 1 : " ) ; 

get s ( Cus t o mer . s z Add r 1 ) ; 

pri n t f ( " Enter address line 2: "); 

get s ( Cus t o mer . s z Add r 2 ) ; 

pri ntf("Enter City: " ) ; 

get s ( Cus t o mer . s z Ci t y ) ; 

pri n t f ( " Enter state postal abbreviation: "); 

get s ( Cus t o mer . s z St at e) ; 

pri ntf("Enter ZIP code: " ) ; 

get s ( s z Buf f er ) ; 

s sc a nf ( s z Buf f er , " %d " , &Cu s t o mer . n Zi p ) ; 
pri ntf("Enter total sales: " ) ; 
get s ( s z Buf f er ) ; 

ssca nf ( s z Buf f er , " %f " , ^Customer. dSal esTotal ) ; 

nResult = f wr i t e ( ( c h a r * ) &C us t o mer , si zeof ( CUSTNAME) , 1, 
Dat a F i I e ) ; 

i f ( n Res u I t 1=1) 

{ 

pri ntf( "ERROR: File ' %s ' , write error.\n", 
s z F i I e N a me ) ; 



f c I os e( Dat a F i I e ) ; 



exi t ( 4) ; 

continues 
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Listing 7.6. continued 

++i ; 

} 

} 

f cl ose( DataFi I e) ; 

} 



I n Listing 7.6, the lines that definethestructurethat holdsthecustomer'sname 
and address usethet y pe def keyword. T his enables us to definethe data object using 
only one line of code: 

CUST NAME Customer; 

This line creates a structure named c u s t omer . As many different structures as needed 
could have been created using the namecusTNAME. 

You access a structure created by a t ypedef in the same way as you access a 
structu recreated by any other method. H owever, nowthecompilerhasadatatypethat 
it can work with, so you can obtain thesi zeofthestructuretypeby referring to itsname. 
Thisisvaluablewhenyou must allocatememoryforthestructure— you cannot get the 
size from the object because it doesn't exist yet! 

The program clears the structure's contents to 0 by using si z e of ( ) with the 
name: 

mems et ( &C u s t omer , 0, si z eof ( CUSTNAME ) ) ; 

I n thecall to me ms e t ( i , you must passtheaddressof thestructure(&cu s t omer ), thevalue 
that you aresettingall thebytesto (o ), and thesizeof thestructure(s i zeof ( c ustname ) ). 
The mems eto C library function then stores the specified value in all the bytes in 

C u s t o me r . 

The rest of CREATEDB is straightforward. The program reads from the 
keyboard each fidd in the structure. Fidds that are not character fidds (such as 
. d s a i esTotai ) are converted to the correct type for thefidd before bang saved in the 
structure. 
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Listing 7.6 does not check the size of the input, so the program 
may fail if an input line is too long. 



Using the offsetof() Macro 



AN SI C introduced a new macro, called of f set of o , that you use to determine the 
offset of a member in a structure. T here are many reasons for wanting to know the 
location of a member in a structure. You might want to write part of a structure to a 
disk fileor read part of a structure in from thefile. 

Usingtheof f setof ( ) macro and simplemath, itiseasytocomputetheamount 
of storageused byindividual membersof a structure. An exampleuseof the-of f setoff) 
macro is shown in Listing 7.7. 

L isting 7.7. OFFSETOF.C. 

/* OFFSETOF, written 1 9 9 2 by Peter D. Hipson 

* This program illustrates the use of the 

* of f s et of ( ) mac r o . 

*/ 

tinclude <stdio.h> // Make includes first part of file 
tinclude <string.h> // For string functions 
# i n c I u d e <stddef.h> // For offsetof() 

#def i ne MAX_SI ZE 35 

int main(void); // Define ma i n ( ) , and the fact that this program doesn't 



/ / use any passed pa r a met er s 



int ma i n ( ) 



i nt 



continues 
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Listing 7.7. continued 



t y pedef struct 
{ 

char 
i nt 
} SAYI NG; 



* s z S a y i ng[ MAX_SI ZE] ; 
nLengt h[ MAX_SI ZE] ; 



t y pedef struct 

{ 



SAYI NG 


Mur phy; 


SAYI NG 


Peter; 


SAYI NG 


Pet er 1 ; 


SAYI NG 


Pet er 2 ; 


SAYI NG 


Pet er 3; 


SAYI NG 


Pet er 4; 



} OURSAYI NG; 



OURSAYI NG OurSayi ng = {{ 

"Firestone's Law of Forecasting:", 

Chicken Little has to be right only once.", 



" Ma n I y ' s Maxim:", 

Logic is a s y s t e ma t i c me t h o d of coming to", 
the wrong conclusion with confidence.", 

" Moe r ' s truism:", 

The trouble with most jobs is the job holder's", 
resemblance to being one of a sled dog team. No one", 
gets a change of scenery except the lead dog.", 

"Cannon's Co mme n t : " , 

If you tell the boss you were late for work because you", 

had a flat tire, the next morning you will have a flat tire.", 

NULL /* Flag to mark the last saying */ 

}, { 

" Dav i d ' s rule:", 

Software should be as easy to use as a Coke machine.", 
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Peter's Max i m: " , 
To be successful, you must work hard, but", 
Hard work doesn't guarantee success.", 



Teacher's truism:", 

Successful people learn. 



PI ayer ' s Comment : " , 

If you don't play to win,", 
you don't win.", 
NULL /* Flag to mark the last saying */ 
}}; 



pr i ntf ( 

"si zeof ( SAYI NG) 

"off setof (OURSAYI NG, Peter) 

"off setof (OURSAYI NG, P e t e r 3 ) 

si zeof ( SAYI NG) , 

of f setof ( OURSAYI NG, Peter), 

of f setof ( OURSAYI NG, P e t e r 3 ) ) 



= %d (each member ' s si z e ) \ n " 
= %d (the second me mb e r ) \ n " 
= %d (the fifth me mb e r ) \ n " , 



return ( 0) ; 



To usetheoff setof ( ) macro, you supply both the structure and the member 
name. In addition, the structure name must be created using typedef because the 
of f setof ( i macro must create the pointer type with a valueof 0, and an identifier — 
not a variable name — is required. 

H ere is another use of the o f f s e t o f ( i macro. Suppose that a structure has 75 
members that consist of strings, structures, and scalar variables. You want to save the 
middle 30 members in a file. You have to know the starting address and how many 
bytes to write to the file. 

You could usethesi zeof ( ) keyword to computethesizeoftheblock of memory 
to write, butthiswould bedifficultand complex. You would haveto get thesizeof each 
member that you want to save to thefile, then add the results. Also, serious problems 
would result if mem berscontained packing bytes (to align them on word boundaries). 
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A better solution is to taketheof f setoff) of the first member to write and the 
of f s e t o f ( i of the member just after the last member to write. Subtract onefrom the 
other, and you have the number of bytes to save. As you can see, this method isquick 
and easy. 

Pointers to Structures 

A pointer to a structureis handled in thesame way asa pointer to any other data type, 
except the syntax of the structure pointer operator differs. You can have a pointer to 
a structure, and use the pointer to access any member in the structure. 

When calling functionsthathavestructures as parameters, it ismoreefficient to 
pass a pointer to a structure rather than pass the entire structure. See Listing 7.8, 
STRUPTR.C. 

Listing 7.8. STRUPTR.C. 

/* STRUPTR, written 1 9 9 2 by Peter D. Hipson 
* Pointers and structures 

*/ 

tinclude < s t d i o . h > // Make includes first part of file 
#include <string.h> // For string functions 

#def i ne MAX_ S I ZE 35 

int main(void); // Define ma i n ( ) , and the fact that this program doesn't 
/ / use any passed pa r a met er s . 

int ma i n ( ) 
{ 

int i ; 

t y pedef struct 
{ 

char *szSayi ng[ MAX_ S I ZE] ; 
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i nt nLengt h[ MAX. SI ZE] ; 

} SAYI NG; 

t ypedef struct 

{ 

SAYI NG Mur phy; 
SAYI NG Peter; 
} OURSAY I NG; 



OURSAYI NG OurSaying = {{ 

"Firestone's Law of Forecasting:", 

Chicken Little has to be right only once.", 



Ma n I y ' s Max i m: " , 

Logic is a s y s t e ma t i c me t hod of coming to", 
the wrong conclusion with confidence.", 



Mo e r ' s truism:", 
The trouble with most jobs is the job holder's", 
resemblance to being one of a sled dog team. No one", 
gets a change of scenery except the lead dog.", 



"Cannon's Co mme n t : " , 

If you tell the boss you were late for work because you", 

had a flat tire, the next morning you will have a flat tire.", 

NULL /* Flag to mark the last saying */ 

}, { 

"David's rule:", 

Software should be as easy to use as a Coke machine.", 

"Peter's Max i m: " , 

To be successful, you must work hard, but", 
Hard work doesn't guarantee success.", 



Teacher's truism:", 

continues 
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Listing 7.8. continued 

Successful people learn.", 



"Player's Co mme n t : " , 

If you don't play to win,", 
you don't win.", 

NULL /* Flag to mark the last saying */ 

}}; 

OURSAYI NG * pOur Sayi ng; 
SAY I NG * pSayi ng; 

pOur Sayi ng = &Ou r Say i ng; 

pSay i ng = StOurSayi ng. Peter; 

p r i n t f ( 



"si z e o f 


( OURSAYI NG) 


= %d \ n " 


"si z e o f 


( Our Sayi ng) 


= %d \ n " 


"si z e o f 


( SAYI NG) 


= %d \ n " 


"si z e o f 


( pOur Sayi ng- >Mur phy) 


= %d \ n " 


"si z e o f 


( pOur Sayi ng- >Pet er ) 


= %d \ n " 


"si z e o f 


( pSayi ng) 


= %d \ n " 


"si z e o f 


( *( pSayi ng) ) 


= %d \ n" 


si zeof 


OURSAYI NG) , 




si zeof 


Our Sayi ng) , 




si zeof 


SAYI NG) , 




si zeof 


pOur Sayi ng- >M u r phy) , 




si zeof 


pOur Sayi ng- >Pet er ) , 




si zeof 


pSayi ng) , 




si zeof 


*( pSayi ng) ) ) ; 





for (i = 0; pOur Sayi ng- >Mur phy. szSayi ng[ i ] ; i + + ) 

{ 

pOurSayi ng - >Murphy. nLength[ i ] = st r I en( pOur Sayi ng- 
>Mur phy. szSayi ng[ i ] ) ; 

} 

for (i = 0; pOur Sayi ng- >Mur phy. szSayi ng[ i ] ; i + + ) 
{ 
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pri ntf( "pOurSayi ng - >Murphy %p %3d '%s'\n", 
&pOu r Say i ng- >Mu r p h y . szSayi ng[ i ] , 
p 0 u r S a y i n g - >Mu rphy.nLength[i], 
pOur Sayi ng - >Mur phy. szSayi ng[ i ] ) ; 

} 

p r i n t f ( " \ n \ n " ) ; 

for ( i =0; pSay i ng- >s z Say i n g [ i ] ; i ++) 

{ 

pSayi ng- > n L e n g t h[ i ] = s t r I e n ( pS ay i n g - >s z Say i n g [ i ] ) ; 

} 

for ( i =0; pSay i ng- >s z Say i n g [ i ] ; i ++) 

{ 

pri ntf("pOurSayi ng->Peter %p %3d ' %s ' \ n " , 
& p S a y i ng- >s z S a y i ng[ i ] , 
pSay i ng- >n Lengt h [ i ] , 
pSayi ng- >s z S a y i ng[ i ] ) ; 

} 

pri ntf("\n\n"); 
return ( 0) ; 



W hen astructureisaccessed with apointer, theusual method of obtaining avalue 
from memory (using the * operator) is unsatisfactory. To access a member of a 
structure pointed to by a pointer, you usethe- > structure pointer operator rather than 
the. structure member operator. The- > operator is used as shown in Listing 7.8. You 
usetheaddr ess of operator to assign the address of the structure to the pointer. 

Understanding unions 

If a structure is a group of related data objects, what is a u n i on? 

I n a structure, each member is stored separately. M odifying one member of a 
structure does not change the contents of any other member. 
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I n a u n i o n , all thememberssharethesameblock of storage. T heblock of storage 
islarge enough to hold thelargest member; smaller membersuseonly asmuch storage 
as necessary. If you changewhatisstored in onememberof a u n i on, all other members 
are changed too. 

Figure 7.1 shows the relationship between a structure and a u n i on in memory. 
This figure shows the relationship between allocated memory and the members that 
are part of the data object. 



struct { 
int nTime, 
int nDay 

char szMessage[20] }, 




Length is 24 bytes. 



Note: with a structure, each member has its 
own storage. Changing the member nTime 
will not change the member nDay's value. 



union ( 
int nTime;- 
mt nDay;- 
char szMessage[20] };' 




Length is 20 bytes. 



Note: with a union, each member shares the 
union's memory with all the other members. 
Changing the member nTime will change 
member nDay's value. 



Figure 7.1. A structure and a union in memory. 



TheU N 10 N .C program in Listing 7.9 reads thedatabasefilecreated with the 
CREATED B.C program (Listing 7.6). U N 10 N .C pi aces the result of the read into a 
union.lt then checks what type of record was read and calls the correct function to 
process the record. 



Listing 7.9. UNION. C. 

/* UNION, written 1 99 2 by Peter D. Hipson 

* This program reads the CREATEDB. C database. The 

* program has minimal error checking; it will fail 

* if you provide a field value that is too long for the 

* structure member that holds it. Use with caution! 
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#i nc I u d e <s t r i n g . h > 

# i n c I u d e <ct ype. h> 

#i nc I ude < s t d i o . h > 

#i nc I ude <pr oces s . h> 

# i n c I ude <s t d I i b . h > 



#d ef i n e C U S T 0 ME R_ R E C OR D 1 
#def i ne SUPPLI ER_ RECORD 2 

// Define the structure for the customer database, 
typedef struct _ CUSTNAME { 



i nt 


nRecordType; 






char 


szName] 61] ; 


/ 60 chars for name; 1 for 


null at end 


char 


szAddr 1[ 61] ; 


/ 60 chars for address; 1 


for null at end 


char 


szAddr 2[ 61] ; 


/ 60 chars for address; 1 


for null at end 


char 


szCi t y [ 2 6 ] ; 


/ 2 5 characters for city; 


1 for null at end 


char 


szSt at e[ 3] ; 


/ 2 - character state abbreviation + null 


i nt 


nZi p; 


/ Use integer; print as %5 


. 5d for leading 0 


i nt 


n Rec o r d Nu mbe r ; 


/ Wh i c h record number? 




d o u b 1 e 


dSal esTot al ; 


/ A mo u n t the c u s t o me r has 


purchased 


} CUSTNAME; 







typedef CUSTNAME near * NPCUSTNAME; 
typedef CUSTNAME * PCUSTNAME ; 

typedef struct SUPPLI ERNAME { 



i nt 


nRecordType; 






char 


szName] 61] ; 


/ 60 chars for name; 1 for 


null at end 


char 


szAddr 1[ 61] ; 


/ 60 chars for address; 1 


for null at end 


char 


szAddr 2[ 61] ; 


/ 60 chars for address; 1 


for null at end 


char 


szCi t y [ 2 6] ; 


/ 2 5 characters for city; 


1 for null at end 


char 


szSt at e[ 3] ; 


/ 2 - character state abbreviation + null 


i nt 


nZi p; 


/ Use integer. Print as %5 


. 5d for leading 0 


i nt 


n Rec o r d N u mbe r ; 


/ Wh i c h record n u mb e r ? 




doubl e 


dSal esTot al ; 


/ A mo u n t the c u s t o me r has 


purchased 



} SUPPLI ERNAME; 



continues 
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Listing 7.9. continued 

typedef SUPPLI ERNAME near *NPSUPPLI ERNAME; 
typedef SUPPLI ERNAME *PSUPPLI ERNAME; 

typedef union _ DBRECORD { 

CUST NAME Customer; 
SUPPLI ERNAME Supplier; 
} DBRECORD; 



/* Local prototypes (use the typedef'ed names, 
* so mus t follow t y ped ef s ) : 

*/ 

SUPPLI ERNAME P r o c es s S u p p I i e r ( N P S U P P L I E RN AME ) ; 
CUST NAME Process Customer ( NPCUSTNAME) ; 

// ma i n ( ) function, the called functions 

void ma i n ( ) 

{ 

DBRECORD dbRecord; 

FILE * Da t a F i I e ; 

char s z F i I e N a me [25]; 
char szBuf f er[ 129]; 

i nt i ; 

i nt nResul t [ 3] ; 

double dSal es = 0.0; // Forces loading of floating-point support 



printf(" Please enter customer database name: "); 
gets(szFileName); 

DataFile = fopen(szFi I eName, " r b " ) ; 
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ccc 



if ( DataFi I e == NULL) 

{ 

p r i n t f ( " E RROR: File ' %s ' couldn't be opened. \ n", s z F i I e N a me ) ; 
exi t ( 4) ; 

} 

nResul t [ 0] = 1; 

whi I e ( nResul t [ 0] == 1) 

{ 

n Re s u I t [ 0 ] = fread((char * ) &d b Rec o r d , si zeof ( DBRECORD) , 1, 
DataFi I e) ; 

i f ( nResul t[ 0] 1=1) 

{ 

if ( ! f eof ( Dat a F i I e) ) 

{ 

pri ntf( "ERROR: File ' %s ' , read error. \ n " , szFileName); 
f c I o s e( Dat a F i I e ) ; 
exi t ( 4) ; 

} 

else 

{ 

pri ntf( "End of database file ' %s ' . \ n " , s z F i I e N a me ) ; 

} 

} 

else 
{ 

// You could test dbRecord. Suppl i er. nRecordType, or 
swi tch(dbRecord. Customer. nRecordType) 

{ 

case CUSTOMER_ RECORD: 

P r o c e s s C u s t o me r ( &d b Re c o r d . C u s t o me r ) ; 

break; 
case SUPPLI ER_ RECORD: 

continues 
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Listing 7.9. continued 



Pr ocessSuppI i er( &d b R e c o r d . Suppl i er) ; 
break; 
def a u I t: 

p r i n t f ( " ERROR: Invalid record type read f r o m \ 
database \ n " ) ; 

break; 



f cl o s e ( Dat a F i I e) ; 

} 

SUPPLI E R NAME ProcessSuppI i er( 

NPSUPPLI ERNAME npSuppI i er ) 

{ 

SUPPLI ERNAME WorkSuppI i er; 
WorkSupplier = * n p S u p p I i e r ; 

printf("Supplier name: %s\n", npSuppI i er - >szName) ; 
Do other processing for Supplier... 

Return WorkSupplier to caller, 
r e t u r n ( Wo r k S u p p I i e r ) ; 

} 

CUST NAME ProcessCustomer( 

NPCUSTNAME npCustomer) 
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ccc 



CUST NAME Wo r k C u s t o me r ; 

Wo r k C u s t o me r = * n p C u s t o me r ; 

printf("Customer name: %s\n", npCustomer - >szName) ; 
// Do other processing for customer... 



// Return WorkCustomer to caller, 
r e t u r n ( Wo r k C u s t o me r ) ; 

} 



An integer that determines the record type is the first field of each of the two 
structures that makeup theu n ion. Another common way to refer to afield likethisis 
to code the definitions as 

t ypedef union _ DBRECORD { 

int nRecor dType; 

CUSTNAME Customer; 
SUPPLI ERNAME Supplier; 
} DBRECORD; 

In this definition, you also have a record type variable as part of theu ni on. You 
can check the value of the record type variable by simply using thefollowing format, 
rather than c u s t o me r or s u p p i i e r : 

DBRECORD dbRecord; 

/* Read a database record into dbRecord */ 

s wi t c h ( d b Rec o r d . n Rec o r dTy pe ) // Rather than // 

// dbRecord. Customer. nRecordType 

{ 

W ith thisformat, thefirst field of each structure must still bean integer that will 
hold therecord type. H owever, you can refer to thefirst field directly, which makesthe 
code easier to read. 
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Summary 

In this chapter, you learned about structures and unions. 

• A structure is a group of related data objects that are stored in a contiguous 
block of memory and can be referred to collectively by a given name. 

• A union is a group of (related) data objects that sharea single block of memory 
and can be referred to collectively by a given name. 

• In a union, usually only one member at a time contains valid data. 

• Thet ypedef keyword enables the programmer to define new data types. T hese 
new data types can besimple variables, arrays, structures, or unions. 

• A bitfield is defined as part of a structure. It consists of a named variable 
whose length is defined as a specific number of bits. 

• Theoff setoff) macro returns the offset of a structure's member, from the 
beginning of the structure. 
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Allocation 

Allocating largedata objects at compiletimeisseldom practical— especially if thedata 
objects are used infrequently and for a short time. Instead, you usually allocate these 
data objects at runtime. 

To make more memory available to the programmer, AN SI C offers a num- 
ber of memory allocation functions, including mai i oco , real i oc( ) , cai i oc{) , and 
f reel ) . M any compiler suppliers complement these functions with similar functions 
that optimize the allocation of memory based on the specifics of your computer's 
architecture. I nth is chapter, you look at these four functions and M icrosoft's enhanc- 
ed versions of them. 



227 



Part 1 1 • Managing Data in C 



Using the mallocO Function 

The memory allocation functions in Table 8.1 include both the AN SI C standard 
ma 1 1 o c ( ) functions and M icrosoft's extensions. 

Table 8.1. Microsoft C mallocO functions. 



Function Description 



void 


ma i i o c t size r. size j , 


1 1 Icnlil Jl V^, JLGI IUQI U 1 1 ICI 1 IUI y 






allnratfnn fiinrHnn 

01 1 ULull Ul 1 1 U 1 ILUUI 1 . 


void 


K 3 f A A 1 / W A 1 A 1 \ % K 1 1 A f 

_ D a s c a i voia j Dmdiioc 


U UCj UGjCU 1 1 Id 1 IUI y 01 1 ULuLI Ul 1 . 


i 


segment seg, size_t size ); 


The memory is allocated from the 






segment you specify. 


void 


far * _ f ma 1 1 o c ( si zetsi ze ); 


Allocates a block of memory 






outside the default data segment, 






returning afar pointer. This 






function is called by ma 1 1 oc( ) 






when thei a r g e Or compact 






memory model is specified. 


void 


_ n e a r *_nmalloc 


Allocates a block of memory inside 


( si 


z e_ t size ) ; 


the default data segment, returning 






a near pointer. T hisfunction is 






called by ma 1 1 o c ( ) whenthesmaii 






or me d i um memory model is 






specified. 



Themai i oco libraryfunction allocatesa block of memory up to thesizeallowed 
by si ze.t . To use ma 1 1 oc( ) , you must follow a few simple rules: 

• Themai i oc ( ) function returns a pointer to the allocated memory or null if the 
memory could not be allocated. You should always check the returned pointer 

for NULL. 

• The pointer returned by ma 1 1 oc( i should be saved in a static variable, unless 
you are sure that the memory block will be freed before the pointer variable is 
discarded at the end of the block or the function. 
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• You should always free a block of memory that has been allocated by ma 1 1 o c ( i 
when you are finished with it. If you rely on theoperating system to free the 
block when your program ends, there may be insufficient memory to satisfy 
additional requests for memory allocation during the rest of the program's run. 

• Avoid allocating small blocks (that is, less than 25 or 50 bytes) of memory. 
There is always some overhead when mai i oc( ) allocates memory— 16 or more 
bytes are allocated in addition to the requested memory. 

Themai i o c ( ) function requires only one parameter: the size of the block of 
memory to allocate. As mentioned, the length of this parameter is si ze_t , which on 
many systems is a short int (16 bits). 

You could assume that you cannot allocate a block of memory larger than the 
AN SI C maximum of 32,767 bytes. Another method isto check thedefined identifier 
(usually in ma 1 1 oc. h) for the maximum for the particular system. With M icrosoft C 
compilers, for example, the maximum is approximately 65,500 bytes. If you assume 
the worst case (the AN SI C value), however, your program has a better chance of 
working if the limit changes. 

The constraint on thesizeof a data object may seem unreasonable, but you will 
rarely reach the 32K limit imposed by AN SI C. If you have large data objects, it is 
always possible (and desirable) to break them into smaller, more manageable pieces. 

I f you are d eterm i n ed to d ef i n e a d ata obj ect I arger th an th e al I o wed si ze ( som e- 
thing I do not recommend) and are using a M icrosoft C compiler, you can use the 
haiioco function. This function allocates an array that can beany size (up to the 
amount of availablefree memory). You must definethearray element size as a power 
of two, which is not an issue if the array is type char , int, or i o n g . If the array is a 
structure, type u n i o n , or a floating-point long double, this constraint may need to be 
addressed with padding. If you use the h a 1 1 oc( ) function, your code will not be 
portable, but you could probably create a workaround if necessary. 

When you use the ma 1 1 oc( ) function, remember that the block of allocated 
memory is not initialized. If you want initialized memory, use memseti ) after the 
memoryisallocatedorusecai i oc( ) (discussed in thenext section). I recommend that 
you always initialize any memory allocated with themai i oc() function. 

Listing 8.1, M ALLOC2.C, allocates blocks of memory. There is no way to 
determinethesizeof thelargestavailableblock, sotheprogram beginswith thelargest 
size (32,767). If ma 1 1 o c ( ) fails, the program reduces this size by 50 percent; this 
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continues until the requested size is less than 2 bytes. The program stops when there 
is no more memory, or a total of 2M has been allocated. 

Listing 8.1. MALLOC2.C. 

/* MALL0C2, written 1 9 9 2 by Peter D. Hipson 
* This program allocates memory. 

*/ 

#i n c I ud e <i o . h > / / I/O functions 

#i n c I u d e < s t d i o . h > // Make includes first in program 

tinclude <string.h> // For string functions 

#i n c I u d e < ma I I o c . h > // For memory allocation functions 

int main (void); // Define ma i n ( ) and the fact that this 

// program doesn't use any passed parameters 

int ma i n ( ) 



int i = 0; 

int j = 0; 

i nt * n P o i nter[ 100] = {NULL}; 

int nSi ze = 3 2 7 6 7; 

long I Tot al Byt es =0; 

w h i I e ( n S i z e > 0 && // Make nSize valid 

nSi ze <= 3 2 7 6 7 && 

I Total Bytes < 2 0 0 0 00 0) // Not more than 2M will be allocated 

{ 

n P o i n t e r [ i ] = (int *)malloc(nSize); 

if ( nPoi nt er [ i ] ! = NULL) 

{ 

++i ; 

I Total Bytes += nSize; 
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pri n t f ( " A I I ocated %5u bytes, total %10ld\n", 

nSi z e, 

I Total Bytes) ; 

} 

else 
{ 

pri ntf("Coul dn' t allocate %5u bytes, total %1 0 1 d \ n " , 
nSi z e, 

I Tot al Byt es ) ; 
nSi ze / = 2; 

} 

} 

for ( j =0; j < i ; j + + ) 

{ 

free(nPointer[j]); 
nPoi nter [ j ] = NULL; 

} 

return ( 0) ; 



Listing 8.1 issystem dependent. If you areusingaPC under DO Sin real mode, 
for example, about 400,000 bytesof memory might be allocated. U nder a protected- 
modeenvironmentsuch asOS/2 or Windows, you can allocatemuch more memory. 
For example, on a system running in protected mode with 10M of freememory, 2M 
of memory might be allocated, as follows: 



Al 1 ocated 


3 2 7 6 7 


bytes, 


total 


3 2 76 7 


Allocated 


3 2 7 6 7 


bytes, 


total 


6 5 5 3 4 


Allocated 


3 2 7 6 7 


bytes, 


total 


9 8 3 0 1 


and so on . . . 










Allocated 


3 2 7 6 7 


bytes, 


total 


1966020 


Allocated 


3 2 7 6 7 


bytes, 


total 


1998787 


Allocated 


3 2 7 6 7 


bytes, 


total 


2031554 



If you arenotsureoftheenvironment in which your application will berunning, 
assume the worst case— less than 32K of free memory. 
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Noticethataloopattheendoftheprogramfreesthememorythatmai i oc() has 
allocated. This loop is performing housekeeping— something that every well-written 
program should do. 

U sing the callocf) Function 

Becausemai i oco doesnot initializememory and cai i oc() does, programmers often 
prefer c a i loco .When using M icrosoft'sC compilers, the array memory allocation 
functions in Table 8.2 are used with cai i oc( ) . 

Table 8.2. Microsoft C callocO Functions. 



Function Description 



void * 


cai 1 oc ( 


si z e _ t num, 


TheANSI C standard array memory allo- 


si ze_t 


size ) 




cation function. 


void 


_ b a s e d ( 


void ) 


Does based memory allocation. You 


*_bcal 1 oc( 


s e g me n t s e g , 


provide the segment that the data will be 


si z e_ t 


n u m, s 


i z e _ t size ) ; 


allocated from. 


void 


Jar *_ 


f cai 1 oc 


Allocates a block of memory outside the 


( size 


_t num, 


si z e_ t 


default data segment, returning afar 


size ) 






pointer. This function is called by cai i oc( ) 








when the large or c o mp a c t memory modd 








is specified. 


void 


_ n e a r * 


_ n c a 1 1 oc 


Allocates a block of memory inside the 


( size 


_t num, 


si z e_ t 


default data segment, returning a near 


size ) 






pointer. This function is called by cai i oc( ) 








when the small or medi um memory modd 








is specified. 



The caiioct) library function allocates memory much like the ma 1 1 oc( ) 
function, with two main differences. With thecal i oc( ) function, you specify two 
parameters, not one: thenumber of dementsandthesizeof each dement. Theproduct 
of th ese param eters determ i n es th e si ze of th e mem ory bl ock to al I ocate, an d m u st f i t 
in types i ze t , which on manysystemsisashortint (16 bits). If you specify an dement 
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size of 1, the cai i oc( i num parameter functions similarly to the maiioco size 
parameter. 

The second difference is that thecal i oco function initializes the memory it 
allocates to zero. The value used to initialize the memory is an absolute zero, which 
usually— but not always— evaluates to a floating-point zero or a null pointer value. 
Thisisfineif thememory will beused for string storageor integers. If thememory will 
beused for floating-point values, you should explicitly initialize theblock of memory 
after c a 1 1 oc( ) returns. I recommend that you alwaysinitializememory allocated with 
cai i oc if you do not know the format of the data that you will be storing in it. 

Tousecai i oc( i ,you follow the same rules for using ma 1 1 oco . These rules are 
outlined in the first section, "Using the mallocO Function." 

Listing 8.2, CALLOC1.C, allocates blocks of memory. The size of the largest 
available block cannot be determined, so the program begins with the largest size 
possible (using the size of i nt ) and tries to allocate an array of 32,767 members. If 
cai i oco fails, the program reduces the size by 50 percent; this continues until the 
requested size is less than 2 bytes. The program allocates buffers, each containing 
32,767 2 -byte integers. W hen an allocation request fails, theprogram decreases the size 
of the array until more memory can be allocated. It stops when there is no more 
memory or 2M havebeen allocated. Theonly major difference between M ALLOC 2.C 
and CALLOC1.C is the call to the memory allocation function. 

L isting 8. 2. CALLOC1.C. 

/* CALL0C1, written 1 9 9 2 by Peter D. Hipson 
* This program allocates arrays of memory. 

*/ 

# i n c I u d e <stdio.h> // Make includes first part of file 
tinclude <string.h> // For string functions 

# i n c I u d e < ma I I o c . h > / / For memory allocation functions 

int main(void); // Define ma i n ( ) and establish that this 

// program does not use any passed parameters 



int ma i n ( ) 

continues 
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Listing 8.2. continued 



nt i = 0; 

nt j = 0; 

nt *nPoi nter[ 100] = {NULL}; 

nt nSi ze = 3 2 7 6 7; 



long I Tot al Byt es =0; 

whi I e ( n S i z e > 0 && // Make nSize valid 

nSi ze <= 3 2 7 6 7 && 

I Total Bytes < 2 0 0 0 00 0) // No more than 2M will be allocated 



{ 



} 



n P o i n t e r [ i ] = (int *)calloc(nSize, sizeof(int)); 

if ( nPoi nt er [ i ] ! = NULL) 

{ 

++i ; 

I Total Bytes += (nSize * s i z eof ( i n t ) ) ; 

pr i ntf ( "Al I ocated %5u short int, total %10ld\n", 

nSi z e, 

I Tot al Byt es) ; 

} 

else 

{ 

pri ntf( "Coul dn' t allocate %5u short int, total %10ld\n", 
nSi z e, 

I Tot al Byt es) ; 
nSi ze / = 2; 



for ( j =0; j < i ; j + + ) 
{ 
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free(nPointer[j]); 
nPoi nter [ j ] = NULL; 

} 

return ( 0) ; 

} 



When CALLOC1 was run, it could not allocate an integer array of 32,767 
members, as the foil owing output shows: 



Couldn't Al 


ocate 3 2 7 6 7 


bytes, 


total 


0 


Allocated 


1 6 3 8 3 


bytes, 


total 


3 2 7 6 6 


Allocated 


1 6 3 8 3 


bytes, 


total 


6 5 5 3 2 


Allocated 


1 6 3 8 3 


bytes, 


total 


9 8 2 9 8 


and so on. . 










Allocated 


1 6 3 8 3 


bytes, 


total 


1965960 


Allocated 


1 6 3 8 3 


bytes, 


total 


1998726 


Al 1 o c at ed 


1 6 3 8 3 


bytes, 


total 


2031492 



The reason for this is not the AN SI C limit of 32,767 bytes in a data object— my C 
compiler does not enforce this limit. T he limit in my compiler is that a data object 
created by c a 1 1 o c ( ) or ma 1 1 o c ( ) cannot be larger than 65,510 bytes. T he array of 
integers consisted of 32,767 members (each 2 bytes long), for a total of 65,534 bytes, 
which is too large. 

CALLOClthen attempted to all ocate the next size, 16,383, and wassuccessful. 



Thet r ee( i functions in Table 8.3 can be used with a M icrosoft C compiler. 
Table 8.3. M icrosoft C free() Functions. 



Using the freed Function 



Function 



Description 



void free( void *memblock ); 



The AN SI C standard array 
memory deallocation function. 



continues 
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Table 8.3. continued 



Function 



Description 



void _ b f r e e ( _ s e g me n t seg, 

void _ b a s e d ( void ) * me mb I o c k ); 



Based memory deallocation. 



void _ f f r e e ( void 
* me mb I o c k ) ; 



far 



Frees a block of memory outside 
the default data segment. 



void n f r e e ( void 
* me mb I o c k ) ; 



near 



Frees a block of memory inside 
the default data segment. 



Thef reel ) memory allocation function was shown in Listings 8.1 and 8.2. Its 
function is to return to the operating system memory that you have allocated. (You 
could think of thememory as borrowed.) M emoryisusuallyalimited resource— even 
when you are running a system with virtual memory— so you must givememory back 
when you are finished with it. 

Thef ree() function i sal most fool proof. Errorscould occur, however, when you 
try to free memory that 

Was not allocated with one of thememory allocation functions; 

H as been released through a prior call to f reel ) or a call to r eai i oci i; 

Is currently in use by another thread in a multithreaded operating system; 

I snot yours to free. 

W hen f r ee 1 1 iscalled, besureyou are passing a valid pointer to it . To makesurethat 
thepointer isvalid, check that it containsNUL l or points to a properly allocated block 
of memory. N ote that f r e e i ) considers a n u l l pointer to be always valid, and treats a 
call with aNun pointer asa no-operation, which meansf reed simplyreturnswithout 
freeing any memory. 

Look at thefollowing variable declarations in theCALLOCl program: 

i nt j = 0; 

i nt *nPoi nter[ 100] = {NULL}; 

i nt nSi ze = 3 2 7 6 7; 
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The pointer array is initialized to null, which is a safe value for initialization because 
it will not cause an error if it is passed to f reeo . In addition, because the loop that 
allocates the memory uses an index into the array of memory pointers (n p o i nteri ] ), 
only valid pointers to allocated blocks of memory will be stored in nPoi ntern . 

In the final cleanup, the memory pointed to by nPoi ntern is freed. The 
following loop resets each pointer to null after the block of memory is freed: 

for ( j =0; j < i ; j + + ) 

{ 

free(nPointer[j]); 
nPoi nt er [ j ] = NULL; 

} 

If theprogramtriestofreeoneof the already freed nPoi ntern slater (becauseof 
a programming error), the null pointer prevents an error that would be caused by 
trying to free a block of memory twice. 



Using the reallocO Function 

When using M icrosoft's C compilers, the array memory allocation functions in 
Table 8.4 areused with real i oc( ) . 



Table 8.4. MicrosoftC reallocO functions. 



Function 



Description 



void *realloc( void 
*membl ock, si ze_t size ) ; 

void b a s e d ( void ) 

* _ b r e a I I o c ( _ _ s e g me n t 
seg, void b a s e d ( void ) 

* me mb I ock, si z e _ t size ) ; 

void _ _ f a r *_frealloc 
( void _ _ f a r * me mb I ock, 
si ze_t size ) ; 



The AN SI C standard array memory 
reallocation function. 

D oes based memory reallocation. You must 
provide the segment that the data will be 
allocated from. 



Reallocates a block of memory outside the 
default data segment, returning afar pointer. 
Thisfunction is called byreai i oc( ) when the 
i arge or compact memory model is specified. 



continues 
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Table 8.4. continued 

Function Description 

void _ _ nea r * nreaiioc Reallocates a block of memory insidethede- 
( void _ _ n e a r * membi oc k, fault data segment, returning a nea r pointer, 
size t size ) ; T his function is called by r ea 1 1 o c ( i when the 

small or medi um memory model is specified. 



Assumethatyou havea program that reads customer recordsfrom thekeyboard 
and stores each in a structure. When the user is finished entering the names, the 
program saves them to disk. You want to be sure that there is enough memory (within 
reason) to hold theentered names, but you do not want to allocate more memory than 
necessary. 

You could call ca 1 1 oco and allocate all availablefreememoryforthestructures. 
This might work, but it wastes a lot of memory. Another method is to call cai i oc( ) 
and allocate a small block, but the program would have to pause to save the 
information, something that might irritate the user. Or you could call cai i oco , 
allocate a small block, call cai i oco again when the block was filled and get a bigger 
block of memory, copy thesmall block of memory to thelarger one, then freethesmall 
block. As you can see, that would require a lot of work. 

The best solution is to call cai i oco to allocate the initial array, then call 
real i oc( i to maketheblock larger. T her ea 1 1 oc( ) function copiesthecontentsof the 
original block of memory to the new block, then frees the original block, so your work 
is minimized. 

Listing 8.3 istheCDB program. LiketheCREATED B program in Chapter 7, 
"C Structures", C D B readsin customer records. U nlikeC R EAT E D B, C D B writesthe 
records entered bytheuser to thefileonlyaftertheuser has finish ed entering the names. 

Listing 8.3. CDB.C. 

/ * CDB, wr i 1 1 en 1 9 9 2 by Peter D. Hi pson 

* This program uses c a I I o c ( ) and real I o c ( ) . It has 

* better error checking than the CREATEDB program, 

* which was presented in Chapter 7. 

*/ 
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#i nc I u d e <s t r i n g . h > 

# i n c I u d e <ct ype. h> 

#i nc I ude < s t d i o . h > 

#i nc I ude <pr oces s . h> 

# i n c I ude <s t d I i b . h > 

#d ef i n e I N C R E ME N T_ A MOU NT 2 

#def i ne CUSTOMER, RECORD 1 
#def i ne SUPPLI ER_ RECORD 2 

/* Define our structure for the customer database. */ 



typedef struct _ CUSTNAME 
int nRecordType; 
char s z Na me [ 6 1 ] ; 
char szAddrl[ 61] ; 
char s z Ad d r 2 [ 61] ; 
char s z Ci t y [ 2 6 ] ; 
char s zSt at e[ 3 ] ; 
long I Zi p; 
int n Rec o r d Nu mbe r ; 
double dSal esTot al ; 
} CUSTNAME; 



1 == Cus t omer record 

60 chars for name, 1 for null at end 

60 chars for address, 1 for null at end 

60 chars for address, 1 for null at end 

25 chars for city, 1 for null at end 

2 - char state abbreviation, plus null 

Use integer, print as %5 . 5 1 d for leading 0 

Wh i c h record number? 

How much customer has purchased 



typedef CUSTNAME 
typedef CUSTNAME 



near * NPCUSTNAME; 
* P CUSTNAME ; 



void 



FILE * Da t a F i I e ; 



PCUSTNAME 
PCUSTNAME 



Customer = NULL; 
TempCustomer = NULL; 



char s z F i I eNa me [ 2 5 ] ; 
char szBuf f er [ 2 5 7] ; 



continues 
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Listing 8.3. continued 

i nt i ; 

i nt nNumber Recor d s = 0 ; 

int n Record = 0; 

i nt n Res ul t =0; 

double dSal es = 0.0; // Forces loading of floating-point support 

Customer = ( PCUSTNAME) cal I oc( si zeof ( CUSTNAME) , 
I NCREMENT_ AMOUNT) ; 

nNumberRecords += I NCREMENTAMOUNT; 

p r i n t f ( " Please enter customer database name: "); 

gets(szFileName); 

Data File = f o pe n ( s z F i I e N a me , "wb"); 

if ( DataFi I e == NULL) 

{ 

printf(" ERROR: File ' %s ' couldn't be opened. \n", szFileName); 
exi t ( 4) ; 

} 

printf("Demo of callocO and real I o c { ) . s i z eof ( CUST NAME ) = %d\n", 
si zeof ( CUSTNAME) ) ; 

n Rec o r d = 0; 

Cust omer [ nRecord] . sz Name[ 0] = 'A'; // To get past w h i I e ( ) first time 

while ( s t r I e n ( Cu s t o me r [ n Rec or d ] . s z Na me) > 0) 

{ 

mems et ( &Cust omer [ nRecor d] , 0, s i zeof ( CUSTNAME) ) ; 

pri ntf( "Enter n a me %d : " , nRecord + 1 ) ; 
gets(szBuffer); 
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szBuffer [ si zeof( Customer! rtRecord] . szName) - 1] = '\0'; 
strcpy( Customer! nRecord] . szName, szBuffer); 

if (strl en(Customer[ nRecord] . szName) > 0) 

{ 

Customer! nRecord]. nRecordNumber = i; 

do 
{ 

pri ntf( "Enter 1 for c u s t o me r , 2 for supplier " ) ; 
gets(szBuffer); 

s s ca nf ( s z Buf f er , "%d", &Customer[ nRecord] . nRecordType); 

} 

while (Customer] nRecord] . nRecordType != CUSTOME R_RECORD && 
Customer] nRecord] . nRecordType != SU P P L I E R_ RECORD) ; 



pri ntf("Enter address line 1 : " ) 
get s ( s z Buf f er ) ; 

szBuffer [ si zeof( Customer [ nRecord 
s t r c py ( Cus t o mer [ nRecord] . s z Add r 1 

pri n t f ( " Enter address line 2: " ) 
get s ( s z Buf f er ) ; 

szBuffer [ si zeof( Customer [ nRecord 
s t r c py ( Cus t o mer [ nRecord] . s z Ad d r 2 



szAddr 1) 
szBuffer; 



. s z Ad d r 2 ) 
szBuffer; 



1] = '\0' 



1] = '\0' 



pri ntf("Enter City: " ) ; 
g et s ( s z B uf f e r ) ; 

szBuffer [ si zeof( Customer [ nRecord] . szCi t y) - 1] = ' \ 0 ' ; 
strcpy(Custo me r[ nRecord]. szCity, szBuffer); 

pri n t f ( " Enter state postal abbreviation: "); 
get s ( s z Buf f er ) ; 

szBuffer [ si zeof( Customer [ nRecord] . szState) ■ 1] = ' \ 0 ' ; 
s t r c py ( Cus t o mer [ nRecord] . szState, szBuffer) ; 

pri ntf("Enter ZIP code: " ) ; 
get s ( s z Buf f er ) ; 

ssca nf ( s z Buf f er , "%ld", & C u s t omer [ nRecord] . I Zi p) ; 

continues 
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Listing 8.3. continued 

pri ntf("Enter total sales: " ) ; 
gets( szBuffer) ; 

sscanf ( s zBuf f er , " %f " , &C u s t o me r [ nRecord] . d S a I esTotal ); 



+ + n Re c o r d; 



if (nRecord == nNumberRecords) 

{ 

TempCust omer = ( PCUSTNAME ) r ea I I oc ( C u s t o me r , 
si zeof ( CUSTNAME) * (nNumberRecords + 
I NCREMENT_AMOUNT) ) ; 

i f ( TempCust omer ) 

{ 

nNumberRecords += I NC RE ME NT _ A MO U NT ; 



pri ntf("real I oc( ) added records, n o w t o t a I is %d \ n " , 
n Nu mbe r Rec o r ds ) ; 



Cust omer = TempCust omer ; 



Customer! nRecord] . szName[ 0] = 'A'; // To get past 

wh i I e ( ) 

} 

else 

{ 

pr i ntf (" ERROR: Couldn't real I o c the buf f er s\ n\ n\ g" ) ; 
- - nRecord; 

Customer [ nRecord] . szName[ 0] = '\0'; 

} 

} 

else 

{ 

Cus t omer [ n Rec o r d ] . s z Na me] 0] = 'A'; // To get past while() 

} 

} 

} 



for ( i =0; i < nRecord; i ++) 
{ 
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pri ntf {'Name ' %1 0 s ' City ' %1 0 s ' State ' %2s' ZIP ' %5 . 51 d ' \ n " , 
C u s t o me r [ i ] . s z N a me , 
C u s t o me r [ i ] . s z C i t y , 
Customer[i].szState, 
C u s t o me r [ i ] . I Z i p ) ; 

} 

nResult =fwrite((char * ) C u s t o me r , 
si zeof ( CUSTNAME) , 
n Re c o r d , 
DataFi I e) ; 

if (nResult I = n Rec o r d ) 

{ 

pri ntf("ERROR: File ' %s ' , write error, record %d.\n", 
s z F i I e Na me , 
i ); 

fcl ose( DataFi I e) ; 
exi t ( 4) ; 

} 

fcl ose( DataFi I e) ; 

} 



By expanding the buffers used for storing data, thedata can besaved in memory 
and written to thedisk at onetime. In addition, summary information such as totals 
could bedisplayed, theuser could edit the entered information, and the information 
could be processed if necessary. The one hitch is that all the user's data that is in 
RAM and not written to thedisk will belost if thecomputer fails. W ith C REAT ED B, 
at most one record would be lost. 

When you write a program in which the user will be entering substantial 
amounts of data from thekeyboard, you should plan for events that might cause the 
lossof information just entered. 0 nesolution to retaining this information is to write 
to the file after the user inputs a record. Summary information can be presented, 
records can be edited, and soon, and the records the user entered can berewritten by 
the program to a master file later as necessary. 
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The real i oc( ) function enables you to have some control over the size of your 
dynamic data objects. Sometimes, however, thedata objects will becometoo largefor 
avail able memory. In CDB, for example, each data object is 228 byteslong. If 40,000 
bytes of free memory were available, the user could enter about 176 records before 
using up free memory. Your program must be able to handle the problem of 
insufficient memory in a way that does not inconvenience the user or losedata. 

Allocating Arrays 

Allocatinganarrayisaneasyprocesswhenyouusecai i oc() . Itsparametersarethesize 
for each element of thearrayandacountof thenumber of array elements. To dynam- 
ically allocate an array at runtime, you simply makea call. 

Refer to Listing 8.4, SO RT ALO C . T heprogram prompts theuser for a number 
of integers, in the range 10 to 30,000. It then creates a list of integers, sorts them, and 
prints the result. 

Listing 8.4. SORTALOC.C. 

/* S0RTAL0C, written 1 9 9 2 by Peter D. Hipson 

* This program prompts for the number of integers to sort, 

* allocates the array, fills the array with random numbers, 

* sorts the array, then prints it, using 10 columns. 

*/ 

#i n c I u d e <s ea r c h . h > 
#i nc I ude <st di o. h> 
#i n c I ud e <pr o c es s . h > 
#i n c I ude <s t d I i b . h > 
#i nc I ude <t i me. h> 

int compare( const void *, const void *); 
i n t ma i n ( ) 

{ 

int i ; 

int *nArray = NULL; 
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i nt nArraySize = 0; 

wh i I e ( n Ar r a y S i z e < 10 || nArraySize > 3 0 00 0) 

{ 

p r i n t f ( " Enter the number of random integers to sort (10 to \ 

3 0,0 0 0): "); 
s c a nf ( " %d " , &n A r r ay Si z e ) ; 

i f( nArraySi ze < 10 | nArraySize > 3 00 0 0) 
{ 

printf(" Error: must be between 10 and 30, 000! \ n") ; 

} 

nArray = (int * ) c a I I oc ( s i z eo f ( i nt ) , nArraySize); 

if ( nArray == NULL) 

{ 

p r i n t f ( " E r r o r : couldn't allocate that much me mo r y ! \ n " ) ; 
nArraySi ze = 0; 

} 



s r a n d ( ( u n s i g n e d ) t i me ( N U L L ) ) ; 

for (i =0; i < nArraySize; i++) 

{ 

nArray[ i ] = r a n d ( ) ; 

} 

gsort(nArray, nArraySize, sizeof(int), compare); 

for ( i =0; i < nArraySize; i +=10) 

{ 

p r i n t f ( " %5 d %5d %5d %5d %5d %5d %5d %5d %5d %5d\n", 



n A r r a y [ 


1 , 




n A r r a y [ 


+ 


1] , 


n A r r a y [ 


+ 


2] , 


n A r r a y [ 


+ 


3] , 


n A r r a y [ 


+ 


4] , 


n A r r a y [ 


+ 


5] , 



continues 
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Listing 8.4. continued 



n A r r a y [ 


+ 


6] 


n A r r a y [ 


+ 


6] 


n A r r a y [ 


+ 


7] 


n A r r a y [ 


+ 


8] 


n A r r a y [ 


+ 


9] 



} 

free(nArray); 
r e t u r n ( 0 ) ; 

} 

i n t c o mp a r e ( 
const void * a, 
const void * b) 

{ 

return ( * { i n t *) a ■ * { i n t *) b) ; 

} 



SO RTALO C illustrates several important points about using the memory al- 
location functions. First, the array is simply declared as an integer pointer called 
nArray. This pointer is initialized with null to prevent an error when thefreeo 
function frees the pointer. Although always initializing variables may seem excessive, 
using an uninitialized variable is a common programming error. 

After c a 1 1 oco allocates the array, it can beaccessed in thesamewayasany other 
array. For example, standard array indexing can be used, as shown in thefollowing: 

for (i =0; i < nArraySize; i+ + ) 

{ 

n A r r a y [ i ] = r a nd ( ) ; 

} 

The loop assigns a random number to each element (indexed by i ). 

After the array is filled, it is passed to theq s o r t ( ) function likeany other array. 
Theqsor t ( ) function can sort almost any type of data. You just give q s o r t ( ) the 
sizeofthearray'sdements,thenumberof elements, and thecomparefunction. (Note: 
The com paref unction in Listing 8.4 is valid for integers but not floating-point values. 
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This is because the compare must return an integer, and a floating-point value may 
differ by less than the truncation value of an integer.) 

Finally, the array is printed in ten columns. There is nothing tricky about this 
portion of the code— one print statement prints ten elements, then the index is 
incremented by ten. 

Global Memory versus Local Memory 

The discussion of local memory and global memory is applicable to computers with 
I ntel 80x86 C PU s. T heseC PU suse segmented architecture, in which adata object can 
be addressed with a full address (consisting of both a segment and an offset from the 
segment) or as an offset (where the segment used is the default data segment). 

Not all operating systemsandcompilersofferaccessto both local memory (found 
in the default data segment) and global memory (located outside the default data 
segment, usually in its own segment). A compiler that offers memory models, such as 
smai i , medi um, i ar ge, and compact , isgenerally found on a PC -typeof computer. The 
discussion in this section pertains to compilers used on an 80x86 CPU. 

For mostcompilers,thememory model determinesthearea from which memory 
will Deallocated. I f your program usesthei ar ge orcompact memory model, thedefault 
memory pool is global. If your program is as ma 1 1 or medi um model program, thede- 
fault memory pool is local. You can always override the compiler's default memory 
allocation area. 

When running in real mode, Intel 80x86 CPU scan access a maximum of 64K 
in each segment. This limitation, and theway thedefault data segment isallocated (it 
isoften used for thestack, initialized data variables, constants, literals, and theheap, 
wh i ch i s wh ere m em ory i s al I ocated fromwhenusingl ocal memory) , affects h ow m u ch 
data a program can have. 

Global memory has its own segment, and thus can have up to 64K in a single 
data object (or more than 64K by using several contiguous segments). To use global 
memory, however, your program must usef ar (4-byte) pointers rather than near (2- 
byte) poi n ters, an d th i s can si ow program execu ti on . I f you n eed to determ i n eth eef f ect 
thishason performance, you could createoneversion of your program with small data 
blocks and near pointers, and theother with largedata blocks and far pointers, then 
run simple benchmarks. 
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Summary 

In this chapter, you learned about memory allocation, how to change the size of an 
allocated block of memory, and how to free memory after it is no longer needed. 

• Themai i oc ( ) function istheAN SI standard method for allocating memory. 
It accepts a single parameter that specifies how much memory should be 
allocated. 

• Thecal i oc ( ) function allocates memory based on the size of the object and 
the number of objects. It is typically used to allocate an array. 

• When memory allocated with one of the memory allocation functions is no 
longer needed, thef r ee ( ) function returns the memory to the operating 
system. 

• Thereai i oc( i function changes the size of a block of memory allocated with 
one of the memory allocation functions. The object's size can be increased or 
decreased. 

• When programming on the PC (and other systems), you can often choose the 
size of the pointer that accesses the allocated memory. T he pointer size affects 
the size of the executable program and the performance of the program. 
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Without files, your program could do nothing. It would be without input, unableto 
provide output, and unableto savetheresult of any of its computations. Fortunately, 
ANSI C offers an excellent collection of file I/O functions. You can writetoafilein 
an unformatted (machine readable) manner, or your program can write to a file in a 
formatted (people readable) manner. 

This chapter deals with all types of I/O : to and from files, the console, and 
other devices. You learn all (at least I hope all) that you will need to develop the I/O 
portions of your programs. The first part of this chapter deals with disk files. The 
second part coversconsolel/O and direct port I/O , including I/O to printer ports and 
communications ports. M uch of the direct port I/O is hardware dependent; the 
discussion applies to a PC -based system. 
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File I/O Basics 



Thissection does not discuss how files are arranged, stored, and managed on thedisk 
drive. That is a topic for a book on operating systems, notabookon C programming. 
Thissection does cover how to use files. 

T he most important part of most programs is their capability to save results or 
thedata theyuse(such asadatabase) toadisk file. All disk files share things in com- 
mon. (Again, this discussion is confined to the PC 's D 0 S operating system.) 

All files have names. T he format for a disk filename is eight characters for the 
name and three characters for the extension. The selection of a file's name and 
extension are generally left to the user, except for files that other applications utilize. 
M any applications suggest an extension (some require it), but few programs place 
restrictions on the name. 

All files have a creation date and time, which is stored in the time stamp. The 
time stamp is updated each time you save changes to the file, so it serves as a file 
modification time stamp. 

All files havea length. Thislength is in the operating system's structure saved for 
each file. When a file consists of only text, it may also contain an EO F (end of file) 
marker, which under DOS is ox i a (Ctrl-Z). 

All files also have attributes, as follows: 

N ormal N o special attributes are set for the file. 

Directory Thefileisa directory. The directory attribute can beused with 



the hidden attribute. 



Hidden 



The file's name is not displayed when you issue a di r com- 
mand without the / A: h option. 



System 



Thefileisused only by the operating system. Generally, only 
thetwo files belonging to the operating system have the system 
attribute. 



Read only 
Archive 



Thefilecan be only read, not written or deleted. 



Thefilehasnot been backed up sinceit was last changed. 
backup andxcopy can use and change thearchive attribute. 
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You can specify the read-only attribute when you create a file. All other attri- 
butes must beset (or cleared) usingtheDOSATTRi b command. You usethesyst em( ) 
function to call theATTRi b command from DOS applications. 

When a file is opened, theprogram typically must specify thefilenameand the 
mode: read, write, or both read and write. If the file is being created, the program 
could specify also whether the file will be read only after it is created. 

T he open functions return an identifier that is a file handle or a pointer to the 
opened file. You use this identifier when you call the read and write functions. W hen 
theprogram has finished with thefile, thefileshould be closed, or if it isatemporary 
work file, deleted. 



Text F iles and Binary Files 

If a text file is displayed on thescreen, it is readable. 1 1 shouldn't contain any special 
characters other than tabs and newlines and is generally formatted so that it pre 
sents information totheuser in an organized manner. M any text files are used only by 
programs, however, even though the files are fully readable (and perhaps even 
understandable). A binary filecan contain any data, including the internal represen- 
tation of numbers, special control characters. 

A problem arises when you use a text file, theC language, and C's interface to 
DOS. C specifies a single character (called the newline character) to signify the end of 
a line. DOS uses two characters (a newline character followed by a carriage return 
ch aracter) to si gn if y th e en d of a I i n e. E ach i s a con trol ch aracter, andassuch,mustbe 
specified using theAN SI C escape sequence, which begins with a backslash character. 

Tospecifyanewline, you usethe\ n character sequence. W hen C encountersthe 
newline character in a string being output to DOS (either to a file or on thescreen), 
C converts it to thetwo-character sequence that DOS expects (a newline foil owed by 
a carriage return). When input is read, C does the opposite, converting the newline 
and carriage return pair to a single newline character. 

This creates a minor problem. When theprogram reads a specified number of 
bytes in a text mode file, each timethenewlineand carriage return pair is encounter- 
ed, the character count is incremented by only 1 (only one newline character is 
counted). If your program readsthestringfromafile,asshownin Figure9.1, thestring 
is only 29 characters long, not the 31 characters stored in thefile. 
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The string stored in a C program 



1' 

The string when stored in a C program 




occupies a total of 29 bytes. 
5 



The newline character 
\n occupies one byte 
in the program, and 
two bytes in a file. 



The string stored in a DOS file 




The string when stored in a DOS file occupies a total of 31 bytes, 
two bytes longer than used when the the string is stored in memory. 



Figure 9.1. A string in memory and in atext mode file. 

The problem arises when the program must go (seek) to a specific place in the 
f i I e. Y ou can n ot assu m e h o w man y ch ar act ers (or bytes) are bet ween a gi ven po i n t an d 
thedesired point. If you havewritten afilecontainingfivedifferentstringsthatareeach 
50 characters I on g ( an d con tai n an u n kn own n u m ber of n ewl i n e ch aracters) , you cou I d 
not get to the beginning of the fourth string, for example, by seeking to character 
number 150. 

To successfully seek in a text file, you must create an index to each string (or 
record). This index is assigned values by using one of the functions that return the 
current placeinafile, such asft ei i o ortgetposi ) .Thesefunctionsreturnthecorrect 
position of a given data object, taking into consideration theconversion of the new- 
line character to a newline and carriage return pair. 

You must save this index to beableto access thestrings randomly. The only al- 
ternative to saving an index is to read the text file sequentially, which may not be 
acceptable based on performance con si derations. 

TheTEXTFILE.C program, shown in Listing 9.1, shows the effects of text 
mode. 

Listing 9.1. TEXTFILE.C. 

/* TEXTFILE, written 1 9 9 2 by Peter D. Hipson 

* This program demonstrates text file 

* newline conversions. 

*/ 

#i n c I u d e < s t d i o . h > // Make includes first part of file 
#i n c I u d e <string.h> // For string functions 
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#i n c I u d e <process.h> // For a b o r t ( ) , spawn(), exit(), etc. 

#i n c I u d e < ma I I o c . h > // For memory allocation functions 

#i n c I u d e <conio.h> // For console getch(), getche(), etc. 

#i n c I u d e <ctype.h> // For character-conversi on functions 



#def i ne MAX_ L I NES 25 

#def i ne MAX_ LENGTH 80 

char szSayi n g [ MA X _ L I N E S ] [ MAX_ LENGTH] 

{ 



9- 



nFirestone's Law of Forecasting: 




\ n " , 


n Chicken Little has to be right only once. 




\ n " , 


n 




\n\n' 


n Ma n 1 y ' s Maxim: 




\ n " , 


n Logic is a systematic method of coming to 




\ n " , 


n the wrong conclusion with confidence. 




\ n " , 


n 




\ n\ n' 


n Moe r ' s truism: 




\ n " , 


n The trouble with most jobs is the job holder's 




\ n " , 


n resemblance to being one of a sled dog team. No one 




\ n " , 


n gets a change of scenery except the lead dog. 




\ n " , 


n 




\n\n' 


n Ca n n o n ' s Comme n t : 




\ n " , 


n If you tell the boss you were late for work because 


you 


\ n " , 


n had a flat tire, the next morning you will have a f 


at 


t i re. \ n " , 


n 




\ n\n' 



int main (void); // Define ma i n ( ) and the fact that this program 
// does not use any passed parameters 

int ma i n ( ) 

{ 

Fl LE * Da t a F i I e = NULL; 

char szFi I eName[ 25] ; 

char szBuf f er [ 2 5 7] ; 

char szMode] 5] = " w\ 0\ 0"; 

continues 
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Listing 9.1. continued 



nt 



i ; 



nt 



nt 



nt 



nNumber Recor d s = 0 ; 
n Rec or d = 0; 
n Res ill t =0; 



long 
long 



I NewPosi ti on = 0; 
I 01 dPosi ti on = 0; 



/* Prompt the user to supply the mode, either lowercase t 

* for a text file or lowercase b for a binary file. 

*/ 

whi I e ( Dat a F i I e == NULL) 



pri ntf( "\nPI ease enter ' t ' for text file, ' b ' for binary: "); 



/* For n o n - Mi c r o s of t C systems, use t o I o we r ( ) (no leading underscore) */ 



p r i n t f ( " \ n P I ea s e enter name of file to write: "); 
gets(szFileName); 

DataFile = f open( szFi I eName, szMode); 

i f ( Dat a F i I e == NULL) 
{ 

pri n t f ( " ERROR: File ' %s ' couldn't be opened. \n", szFileName); 

} 



whi I e( szModel 1] ! = ' b' && s z Mod e [ 1 ] I = ' t ' ) 



s z Model 1 ] = _t ol o wer ( get c he( ) ) ; 



p r i n t f ( " \ n " ) ; 



swi t ch( sz Model 1] ) 



case ' t 
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pri ntf("Demo of a text f i I e \ n \ n " ) ; 
break; 

case ' b' : 

pri n t f ( " De mo of a binary f i I e\ n \ n " ) ; 
break; 

} 

for ( i =0; s t r I en ( s z Say i ng [ i ] ) ; i ++) 

{ 

I 01 dPosi t i on = f t el I ( Dat a F i I e) ; 

fwrite(szSaying[i], 

s t r I en ( s z Say i ng [ i ] ) , 
1, 

Dat a F i I e ) ; 

I NewPosi ti on = ftell (DataFile); 

pri n t f ( 

"Start position %5I d " 

"end %5I d, " 

" st r I en( . . . ) %d but " 

"wrote % 5 1 d bytes' \ n", 

I 01 dPosi t i on, 

I NewPosi t i on, 

s t r I en ( s z Say i ng [ i ] ) , 

( I ong) I NewPosi t i on - I 01 dPosi ti on) ; 

} 

f c I os e( Dat a F i I e) ; 
p r i n t f ( " \ n " ) ; 

s wi t c h ( s z Mod e[ 1] ) 

{ 

case ' t ' : 

pri ntf("Note the bytes written don't" 
" equal the string's I e n g t h \ n \ n " ) ; 
break; 

continues 
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Listing 9.1. continued 

case ' b' : 

pri ntf("Note the bytes written always" 
" equal the string's I ength \ n \ n") ; 
break; 

} 

return ( 0) ; 

} 



TEXT FILE enables you to open thefilein text modeor binary modeso you can 
seehowthemodesdiffer.Thef tei i o function returns the number of bytesin thefile, 
without regard tothefile'smode. All strings in TEXT FILE have thesame number of 
characters, according to s t r i en() , but the number of bytes written in thetextmode 
depends on the number of newline characters in the string. 

Virtually all files saved by editors and other programsareequivalent to a text file. 
M any DOS programs cannot read a file that does not have the newline and carriage 
return combination. 



Creating and Using Temporary Work Files 

When you create a temporary work file, remember thefollowing simple rules: 

• Thefilenamemust be unique. This uniqueness can beguaranteed by using 

t mpf i I e ( ) Or t mp n a m( ) . 

• Thefilemust be deleted when you have finished using it. If you create thefile 
using t mpf i i e( i , the operating system deletes the file for you. If you create it 
with t mpnami ) and an explicit open, your program must delete the file. 

Few programs can store all their data in memory. You cannot be sure of the 
amount of memory available to your program for data storage, and you therefore 
won't know if there will be enough memory to load the data the program requires. 

M any larger programs with largedataobjectsdo not even try to saveall their data 
in memory. T hey read the data, index the data, then write the data to a temporary 
work file. Listing 9.2, ED LI N E, isasimpleeditorthatreadsatextfile, provides editing 
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capabilities, then writes the program's buffers out to thefile when the user ends the 
program. Because this editor is simple, it supports only line-number editing. 

L isting 9. 2. EDLINE.C. 

/ * EDLI NE, wr i 1 1 en 1 9 9 2 by Peter D. Hi pson 

* This program is a simple line-oriented editor. If 

* your compiler supports memory mo dels, use the 

* large mo d e I . 



*/ 

#i nc 


ude 


<s t d i o . h > 


// Make 


includes first part of file 


#i nc 


ude 


<s t r i n g . h > 


// For 


string functions 


#i nc 


u d e 


<pr oces s . h> 


// For 


abort(), spawn(), exit(), etc. 


#i nc 


ude 


< ma 1 1 o c . h > 


// For 


me mo r y allocation functions 


#i nc 


ude 


<c o n i o . h > 


// For 


console getch(), getche(), etc 


#i nc 


ude 


<ct ype. h> 


// For 


character conversion functions 


#def 


ne 


MAX_ LI NES 


15500 / 


* Allow 6 4 K for indexes 


#def 


n e 


MAX_ LENGTH 


513 / 


* Longest line is 512 + NULL 


#def 


ne 


DELETED LI NE 


- 1 / 


* A line that has been deleted 



long I Li nel ndex[ MAX_ L I NES] ; 
char szl nput Li ne[ MAX_LENGTH] ; 



i n t ma i n ( 

int argc, /* Count of arguments */ 

char *argv[], /* Array of pointers to arguments */ 

char * e n v p [ ] /* Array of pointers to environment */ 



int Ed i t L i n e ( c h a r * s z I n p u t L i n e ) ; /* Used to edit a given line */ 



int ma i n ( 

int argc, 
char *argv[], 
char *envp[ ] 
) 

continues 
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Listing 9.2. continued 



FILE * Da t a F i I e = NULL; 
FILE *Wor k F i I e = NULL; 

char s z F i I e N a me [25]; 

char szBuf f er[ 257]; 

char s z Te mp Na me [ L _t mp n a m] ; 

char s z Ne wNa me [ L_ t mp n a m] ; 

char s z Co mma nd [ 81]; 

char c h Ch a r ; 

i nt i ; 

i nt n Max L i n es =0; 

i nt nStartLi ne; 
i nt nEndLine; 

/* First, get the filename to edit */ 

if ( a r g c >= 2) 
{ 

Dat a F i I e = f o pe n ( a r g v [ 1 ] , " r t " ) ; 

i f ( Dat a F i I e == NULL) 

{ 

pr i ntf ( " ERROR: File ' %s ' couldn't be opened. \n", a r g v [ 1 ] ) ; 

} 

else 

{ 

s t r c py ( s z F i I e Na me, a r g v [ 1 ] ) ; 

} 

} 

whi I e ( Dat a F i I e == NULL) 
{ 

printf("\nPlease enter name of file to edit: "); 
gets(szFileName); 
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DataFile = fopenfszFileName, " r t " ) ; 

if ( DataFi I e == NULL) 
{ 

printf(" ERROR: File ' %s ' couldn't be opened. \n", szFileName); 

} 

} 

p r i n t f ( " \ n " ) ; 

/* Next, get a temporary filename, read the original file, and 

* write it to the work file. Create a line-number index so that 

* you can access the records. 

*/ 

t mp n a m( s z Te mp Na me ) ; 

if (strlen(szTempName) == 0) 

{ 

p r i n t f ( " Co u I d n ' t get a work file name. . . \ n" ) ; 
exi t ( 4) ; 

} 

WorkFile = f o pen ( s z Te mp Na me , "w+t"); 

for ( i =0; i < MAX_LI NES; i + + ) 

{ 

I Li nel ndex[ i ] = DELETED LI NE; 

} 

n Ma x L i n e s = 1 ; 

I Li nel ndex[ nMaxLi nes] = 0; 

wh i I e ( f g et s ( s z I n p u t L i n e , s i z eof ( s z I n p u t L i n e ) , DataFile)) 
{ 

ILinelndex[nMaxLines++] = ftell(WorkFile); 
fputs(szlnputLine, WorkFile); 

} 

fcl ose( DataFi I e) ; 

continues 
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Listing 9.2. continued 

p r i n t f ( " T o t a I lines in file %d . \ n " , n Ma x L i n e s - 1 ) ; 
s zCo mman d [ 0] = ' \ 0' ; 

wh i I e ( s z Co mma n d [ 0] != ' q' ) // Quit without saving (use w command to 

/ / save) 

{ 

pri ntf( "Co mma n d ? " ) ; 
get s ( s z Comma nd ) ; 
s t r I wr ( s z Co mma n d ) ; 
nEndLine = -1; 

ssca nf ( &szCo mmandl 1] , " %d%d " , 
&nSt a r t L i n e , 
& n E n d L i ne) ; 

if (nEndLine < nStartLi ne) 

nEndLine = nStartLi ne; 



f (nEndLine >= n Max L i n es ) 

nEndLine = (nMaxLines - 1); 



wi t c h ( s z Co mma n d [ 0 ] ) 

case ' e' : / * Edit the specified line */ 

if ( nSt a r t Li ne == 0) 
{ 

pri ntf( "Line number must be 1 to %d\n", nMaxLines); 

} 

else 

{ 
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if ( I Li nel ndex[ nStartLi ne] == DELETEDLINE) 

{ 

pri ntf( "Li ne %d has been deleted, " 
"and cannot be edited. \n", 
nStartLi ne); 

} 

if ( n St a r t L i n e < n Max L i n es && 

I Li nel ndex[ nStartLi ne] I = DELETED LI NE) 

{ 

f s e e k ( Wo r k F i I e , 

I Li nel ndex[ nStartLi ne] , SEEK SET) ; 

f get s( sz I nputLi ne, 

si zeof( szl nputLi ne) , WorkFile); 

if ( Edi tLi ne(szl nputLi ne) ) 

{ 

f seek( Wo r k F i I e, 0, SEEKEND) ; 

I Li nel ndex[ nStartLi ne] = ftell(WorkFile); 

fputs(szl nputLi ne, WorkFile); 

} 

} 

} 

break; 

case ' I ' : /* List the specified line */ 

if ( nSt ar t Li ne == 0) 

{ 

nSt ar t Li ne = 1; 

whi I e( nStart Li ne < nMaxLines) 

{ 

if ( I Li nel n d ex [ nStartLi ne] I = DELETEDLI NE) 

{ 

fseek(WorkFi I e, 

I Li nel ndex] nStartLi ne] , SEEK SET) ; 



continues 



261 



Part 1 1 • Managing Data in C 



Listing 9.2. continued 

fgetsfszlnputLi ne, 

sizeof(szlnputLine), WorkFile); 

p r i n t f ( " %4 d - %s " , 
n S t a r t Li n e, 
szl nputLi ne) ; 

} 

el se 

{ 

pri ntf ( "%4d *** DELETED LI NE***\ n", 
n S t art Li ne) ; 

} 

+ + n S t ar t Li ne; 



nStartLi ne = 0; 

} 

else 

{ 

wh i I e( nStartLi ne <= n E n d L i ne) 

{ 

if ( I Li nel n d ex [ nStartLi ne] I = DELETEDLI NE) 

{ 

f s e e k ( Wo r k F i I e , 

I Li nel ndex[ nStartLi ne] , SEEK SET) ; 

fgets(szl nputLi ne, 

si zeof( szl nputLi ne) , WorkFile); 

pri n t f ( " %4 d - %s " , 
nStartLi n e, 
szl nputLi ne) ; 

} 

el se 

{ 

pri ntf ( "%4d *** DELETED LI NE***\ n", 
nStartLi ne) ; 

} 
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+ + n St a r t L i n e ; 

} 

} 

break; 

case ' d' : /* Delete the specified line */ 

if (nStartLine > 0 && 

nStartLine < nMaxLines) 

{ 

printf("Do you really want to delete line %d? (y|n) ", 
nStartLine); 

chChar = get chef ) ; 

p r i n t f ( " \ n " ) ; 

if (chChar == ' y' | | chChar == ' Y ' ) 

{ 

I Li nel ndex[ nStartLi ne] = DELETED LI NE; 

} 

} 

break; 

case 'w': /* Write; continue editing? */ 

szNewNamel 0] = ' \ 0' ; 

t mpn a m( s z Ne wNa me ) ; 

if (strlen(szNewName) == 0) 
{ 

printf(" Error getting a temporary file name. . . \ n " ) ; 

} 

renamefszFi I eName, szNewName); 
Data File = f o p e n ( sz Fi I eName, "wt"); 
nStartLine = 1; 

continues 



263 



Part 1 1 • Managing Data in C 



Listing 9.2. continued 



while(nStartLine < nMaxLines) 

{ 

if ( I Li nel ndex[ nStartLi ne] ! = DELETED LI NE) 



{ 



f s e e k ( Wo r k F i I e , 

I Li nel n d ex [ nStartLi ne] , SEEKSET) ; 

f get s ( s z I nputLi ne, 

si zeof( szl nputLi ne) , WorkFile); 

f put s ( s z I nputLi ne, Dat a Fi I e ) ; 

} 

++n St a r t L i n e; 

} 

nStartLi ne = 0; 
f c I o se( Dat a F i I e ) ; 

/* In this version, the original file is simply deleted. 

* A better programming practice is to rename it to . B A K 

* so the user can recover the original file. 

* 

* Question: 

* When renaming to . BAK, does the user recover from the 

* last save or the original file? 

*/ 

remove(szNewName); /* Could be renamed to .BAK */ 
break; 

case ' q ' : /* Quit, with no save */ 

break; 
default: 

p r i n t f ( " E r r o r : the c o mma n d ' %c ' is not supported! \ n" 
sz Command! 0] ) ; 
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break; 

} 

} 

fcl ose(WorkFi I e) ; 
r e mo v e ( s z Te mp Na me ) ; 
return ( 0) ; 

} 

i nt Edi t Li ne( 

char * szlnputLine) 

{ 

char chChar = 'A'; // To fool while() the first time! 
int nCur rent Char =0; 

p r i n t f ( " %s " , szlnputLine); 

while ( c h Ch a r ) 

{ 

chChar = get ch( ) ; 
if (chChar == ' \ 0' ) 

{ 

chChar = getch( ) ; 

s wi t c h ( c h Ch a r ) 

{ 

case ' \ x4D' : 

p r i n t f ( " %c " , s z I n p u t L i n e [ n C u r r e n t C h a r ] ) ; 

+ + n C u r r ent Char ; 

break; 

default: /* No other keys implemented yet */ 
p r i n t f ( " \ a " ) ; 
break; 

} 

continues 
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Listing 9.2. continued 

} 

else 

{ 

swi tch( chChar) 

{ 

case ' \ n' : 
case ' \ x 0 d ' : 

chChar = ' \ 0' ; 

break; 

default: /* Change current character to typed character */ 
s z I n p u t L i n e [ n Cu r r e n t Cha r ] = chChar; 
p r i n t f ( " %c " , s z I n p u t L i n e [ n C u r r e n t C h a r ] ) ; 
++n C u r r e n t Ch a r ; 
break; 

} 

} 

} 

p r i n t f ( " \ n " ) ; 
r et u r n ( 1 ) ; 

} 



Two parts of ED LIN E require closer examination. First, the program declares 
two character-string buffers to hold temporary filenames: 

char s z Te mp Na me [ L _t mp n a m] ; 
char s z Ne wNa me [ L_ t mp n a m] ; 

I don't know how I on g th ese buffers sh ou I d be, sol usethe L_t mpnam identifier, 
which is defined in stdi o. h . This identifier is system dependent and islarge enough 
to hold any temporary filename returned by t mpnami ) . 

Now that there is a place to save thetemporary filenames, I can call theAN SI 
C t mpnami ) function, which returnsauniquefilename. Thisfilenamecan beusedfor 
any purpose (EDLINE, for example, uses it for a work file). In a multitasking 
environment, the same name might be returned to more than one program. Your 
application can handle this situation by getting a new temporary name if a file is 
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opened for writing and an error is returned because another application is using 
the name. There is no need to signal an error to the user; simply recover by getting a 
new name. 

T hefollowing code shows how a temporary filename is obtained and opened: 

t mp n a m( s z Te mp Na me ) ; 

if ( s t r I e n ( s z Te mp Na me ) == 0 ) 

{ 

pri ntf("Coul dn't open a work f i I e . . . \ n " ) ; 
exi t ( 4) ; 

} 

The recovery in a multitasking environment could be coded as follows: 

Wo r k F i I e = NULL; 

whi I e ( WorkFi I e == NULL) 

{ 

t mp n a m( s z Temp Na me ) ; 

if (strlen(szTempName) == 0) 

{ 

pri ntf("Couldn't get a work file na me . . . \ n" ) ; 
exi t ( 4) ; 

} 

/* fopen() fails if the name has been used by 
* another application 

*/ 

WorkFi I e = f open( szTempName, "w+t"); 

} 

I n general, thistypeof error checking isunnecessary for programsrunning on the 
PC under DOS. 

When you are finished with your work file, you must delete it. You can do this 
with theAN SI C removed function or theun i i nko function, which isstill found on 
manyC compilers. 

AN SI C alsosupportsthetmpf i i e( ) function, which createsatemporaryfileand 
opens the file. This function does much of the work for the programmer, but it has 
disadvantages. For example, when thefileisclosed (whether or not you arefinished), 
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it isdeleted. This makes it impossible to close thefileearly in theprogram'sexecution 
and reopen it later. You also cannot specify the mode of the file: it is opened in the 
binary read/ write mode. E D L I N E required a temporary work file with thetext mode, 
not the binary mode, so t mpf i i e( ) could not be used. 

Thecallstot mpf i i e( ) are easy to make, asshown in thefollowinglinesof code: 

FILE *TempFi I e = t mpf i I e( ) ; 
/* Lines of code to use the file */ 
f cl ose( TempFi I e) ; 

Thetmpf i i e( ) function is handy when thefile's attributes (binary read/write) 
are suitable to your program's needs, and when you want the system to automatical- 
ly delete the file. 

Sometimes you will want the temporary file to stay around. If the program 
crashes, for example, you may be able to recover the user's data from the temporary 
work file. 

U sing a temporary work file is similar to using any other file, except it must be 
deleted and its name must be unique. 

Stream Files and Default File Handles 

In C, files can be opened as stream files, which are identified with a pointer to a f i le 
structure, oraslow-level files, which areidentified with an integer handle. Thissection 
covers stream files. Low-level files aredescribed later in thechapter, under "Low-Level 
I/O and File Handles." 

A stream file must be opened with oneof thefollowing functions: 

f ope n ( i Opens the specified filewith the specified mode 

f reopeni ) Closes the file specified, then opens a new file as specified 

f do pe n ( i Opens a duplicate stream filefor an already open low-level 

file 

If afileisopened with o pen ( ) or oneof theother fileopen functions that return 
an integer handle, thefileisa low-level file, notastream file. T able9.1 lists the stream 
functions that C supports. 
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Table 9.1. Stream file functions (including M icrosoft's additions). 



Function 


Description 


_f so pen ( ) 


M icrosoft's shared file open. 


c 1 ea r er r ( ) 


Clears the current error condition flags. 


f cl os e( ) 


Closes the specified file. 


f c 1 o s ea 1 1 ( ) 


Closes all open stream files. 


f d o p e n ( ) 


Opens a low-level file as a stream file. 


f eof () 


C hecks for end-of-file in a stream file. 


f er r o r ( ) 


Tests for a read or write error. 


ff 1 u s h ( ) 


Flushes pending I/O for a file. 


f get c( ) 


G ets a character from a stream file. 


f g et c h a r ( ) 


Gets the next character from a file. 


f get pos( ) 


Gets a file's current position, for usebyt set post ) . 


f gets( ) 


G ets a string from the specified file. 


f i 1 eno( ) 


Returns the low-level filehandlefor a stream file. 


f 1 ushal 1 () 


Flushes pending I/O from all opened files. 


f o p e n ( ) 


Opens a stream file. 


f putc() 


W rites a character to the specified file. 


f put char ( ) 


W rites a character to the specified file. 


f puts( ) 


Writes the buffer to the stream file. 


f r ea d ( ) 


Reads from the specified stream file. 


f r eo pen ( ) 


Reopens the file. 


f scant ( ) 


D oes a formatted read from a stream file. 


f s e e k ( ) 


Sets thefile's current position as specified. 


f s et pos ( ) 


Setsthefileto the position obtained by f get post ) . 


f tel 1 ( ) 


Gets the file's current position. 



continues 
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Table 9.1. continued 



Function Description 

f writeo Writes to a specified file. 

get c < ) G ets a character. 

get chart ) G ets a character from s t <j i n . 

getso Getsa string from st di n. 

get w< i Getsan integer from the specified file. 

pri ntf ( i D oes a formatted writeto stdout . 

put c { ) Writes a character to a stream file. 

putchari i W rites a character to stdout . 

putsi i W rites a buffer to stdout . 

putwo Writes an integer value to a file. 

rewi nd( ) Sets thefile's current position to thebeginning of thefile. 

rmt mpo R em oves (deletes) temporary files opened with tmpf i i e( ) . 

s c a n t ( i D oes a formatted read from s t d i n . 

set but o Sets the stream file's buffer. 

s e t v b ut ( ) Sets the stream file's buffer (variable size buffer). 

spri ntf ( i D oes a formatted writeto a string. 

sscanf ( i Reads formatted input from a string. 

t e mp n a m( ) G ets a temporary filename, allowing the specification of a 
different directory. 

tmpf i i e( i Opens a uniquely named temporary work file. When thefile 
isclosed or theprogram ends, thefile is deleted. 

t mp n a m( ) Returns a unique name for use as a temporary filename. 

unget c( i Puts back a character to a file opened in the read mode. The 
character put back does not need to be the same as the one 
read, but only one character can be put back at a time. Two 
successivecallstoungetci i without an intervening read will 



fail. 
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Function 

1 UIILU wll 


D pscrintion 


v t p r i n 1 1 ( ) 


U Ocb d lOllTldllcU WllLcLO Lllc b|JcUI IcU Illc. 1 llcOUL|JUL lb 




pointed to by a parameter- list pointer. 


v p r i nt f ( ) 


Does a formatted writeto stdout . The output is pointed to 




by a parameter- list pointer. 


v s p r i n t f ( ) 


Does a formatted writeto the specified string. Output is 




pointed to by a parameter- list pointer. 



The classification of stream files includes a number of standard files. For every 
C program, fivestandardfilesarealwaysopen. Programscan use thesefilesto perform 
basic file I/O to the screen and the keyboard. 

Before describing the standard files, remember that most operating systems 
enableyou to redirect files. Usually, a simple redirection symbol automatically allows 
a file to be used for input or output; the program uses this file as if it were either the 
keyboard or the screen. 



The stdin File 

Thest di n fileisopened by the operating system and isconsidered to bethe keyboard. 
If the operating system supports I/O redirection, however, stdi n could beafile. 

If stdi n 'sin put comes from an I/O redirected file, several problemscan occur 
when theend of the redirected file is reached. First, the program receives an end-of- 
file (eof ) error. M any programs do not adequately check for eof , and the user may 
haveadifficulttimeendingtheprogram. Second, theoperatingsyst em doesnotswitch 
back to thekeyboard. You can force your program to use the keyboard by opening a 
file called con: (under DOS on a PC), but this requires a lot of programming. 

Thefollowing functions use stdi n: 

get c ha r ( ) G ets a character from s t d i n 

get s ( ) Getsa string from stdi n 

s c a n f ( ) Performs a formatted read from stdin 

Thesefunctionsmakeyourcodeeasierto read and understand. Each hasacoun- 
terpart that can be used for any other stream file. 
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Thestdout File 

Thestdout file is opened by the operating system and isconsidered to bethescreen. 
If the operating system supports I/O redirection, however, st do ut could beafile. 

If st do ut 's output goes to a redirected file, several problems can occur. The 
program could receive an end-of-file(EOF ) error when thedisk isfull. M any programs 
do not adequately check for eof with stdout , and the user may not realize an error 
has occurred until theprogram has finished running. Another problem isthat thereis 
no provision to switch back to thescreen. You can forceyour program to usethescreen 
by opening a file called con: (under DOS on a PC), but doing so requires a lot of 
programming. 

The following functions uses t do ut : 

p r i n t f ( ) Performs a formatted write to stdout 

putcnaru W rites a character to s t d o u t 

putso Writes the buffer to stdout 

v p r i n t f ( ) Performs a formatted write to stdout . The output is 
pointed to by a parameter-list pointer. 

Eachstdout function hasa counterpart that can beused for any other stream file. 
And like the s t d i n functions, thestdout functions enable you to write code that is 
easier to read and understand. 



Thestderr File 

Thestderr fileis similar to thes t d o u t file; data written to stderr is displayed on the 
screen. T he major difference is that stderr is used for error messages that you would 
not want redirected to a file if the user is using I/O redirection. You can uses t de r r to 
display messages to the user regardless of whether I/O redirection is used because 
stderr is never I/O redirected. 

No functions use stderr directly. You can usefprintto to write your error 
message: 

f pr i ntf ( st der r , 

"The input file is in the old f o r ma t . Run R E F MT first"); 
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The error message wi 1 1 n ot be red i rected if theoperating system 'sl/O red i recti on 
is in effect. 

Alwaysusestder r fortheprogram'sbannermessage(themessagetotheuserthat 
describes the program and lists the copyright, author, and soon) and error messages. 
If you develop oneerror message function that is always called when an error occurs, 
you can be surethat the message is written to thecorrect place— thescreen andnota 
redirected file. 



The stdaux F ile 

Thest da ux file'snameisabit confusing. What istheaux device? I n AN SI C, theaux 
device is defined asthemain serial communication port (not the console serial com- 
munication port). On a PC, aux is defined ascoMi: , and stdaux writes to the comi : 
port. 

Theshort program in Listing 9.3, called STDAUX. C, writes 100 lines to the 
stdaux file. Before running this program, initialize the communications port. To do 
this under DOS on the PC, use the mode command. 

L isting 9. 3. STDAUX. C. 

/* STDAUX, written 1 9 9 2 by Peter D. Hipson 

* This program uses the stdaux file. It should be run 

* only under DOS on a PC. 

*/ 



tinclude <stdio.h> // Make includes first part of the file 

tinclude <string.h> // For string functions 

# i n c I u d e <stdlib.h> // Standard include items 

# i n c I u d e <process.h> // For exit(), etc. 



int ma i n ( // Define ma i n ( ) and the fact that this program 

i n t a r g c , / / uses the passed p a r a me t e r s 
char * a r g v [ ] , 

continues 
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Listing 9.3. continued 



char 



* e n v p [ ] 



i n t ma i n ( 



i nt 

char 

char 



argc, 

* a r g v [ ] , 

* e n v p [ ] 



i nt 



for ( i =0; i < 100; i ++) 

{ 

/* Because stdaux is opened in the binary mode, 
* CR/LF must be supplied explicitly, using \n\r 

*/ 

fpri ntf(stdaux, 



"Li ne %2d of 100 I i nes" 

" being written to stdaux by a program. \n\r", 



Thestdpr n file is easy to understand. It provides a simple way to write to the system 
printer without having to explicitly open a file. T hes t d p r n file cannot be redirected 
and therefore should beused only for itemsthat will beprinted, probably in response 
to a user request. 



return ( 0) ; 



The stdprn File 
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The short program in Listing 9.4, called STD PRN .C, writes to stdpr n . Before 
running this program, be sure a printer is connected to the primary printer port and 
is online. 

L isting 9.4. STDPRN.C. 

/* STDPRN, written 1 9 9 2 by Peter D. Hipson 

* This program uses the stdpr n file. It should be run 

* under DOS on a PC. 

*/ 



#include <stdio.h> // Make includes first part of file 

tinclude <string.h> // For string functions 

# i n c I u d e <stdlib.h> // Standard include items 

tinclude <process.h> // For exit(), etc. 



int ma i n ( // Define ma i n ( ) and the fact that this program 

i n t a r g c , / / uses the passed p a r a me t e r s 
char * a r g v [ ] , 
char * e n v p [ ] 
) ; 



int ma i n ( 

int a r g c , 
char * a r g v [ ] , 
char * e n v p [ ] 
) 



{ 



i nt 



for ( i =0; i < 50; i + + ) 

{ 

/* Because stdprn is opened in the binary mode, 
* CR/LF must be supplied explicitly, using \n\r 

*/ 

continues 
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Listing 9.4. continued 

fpri nt f ( s t dp r n, 

"Line %2 d of 50 lines" 

" being written to stdprn by a program. \ n\r", 



/* An explicit formfeed is used to force a page eject 
* if the printer is a laser printer 

*/ 

f p r i n t f ( s t d p r n , " \ f " ) ; 
return ( 0) ; 

} 



Thisprogramshowshoweasyitistouseaprinterfrom aC program. Listing 9.5 
isamoreflexibleprogram— theusercan choosethescreen,thecommunicationsport, 
or the printer. 

Listing 9.5. STDFILE.C. 

/* STDFILE, written 1 9 9 2 by Peter D. Hipson 

* This program prints to the selected destination. It 

* should be run under DOS on a PC. 

*/ 



tinclude <stdio.h> // Make includes first part of file 

tinclude <string.h> // For string functions. 

#i n c I u d e <stdlib.h> // Standard include items. 

#include <process.h> // For exit(), etc. 



n t ma i n ( 
i nt 
char 
char 
) ; 



a r g c , 
< a r g v [ 
'envpl 



// Define ma i n ( ) and the fact that this program 
/ / uses the passed par a met er s 
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i n t ma i n ( 



i nt 

char 

char 



a r gc , 

* a r g v [ ] , 

* e n v p [ ] 



FILE * Out put F i I e = NULL; 



i nt 



n F i I e = 0; 



i nt 



i ; 



while (nFile < 1 || nFile > 3) 

{ 

p r i n t f ( 

" Wh i c h file to write to: \ n " 

1 - s t d p r n (the pri nter)\n" 

2 - stdaux (the communications port)\n" 

3 - s t d o u t (the c o n s o I e ) \ n " 
enter 1 , 2 or 3 : " ) ; 

scant ( " %d" , &n F i I e ) ; 



s wi t c h ( n F i I e ) 

{ 

case 1: 

Out p ut Fi I e = s t d pr n ; 
break; 

case 2: 

Out put Fi I e = stdaux; 
break; 

case 3: 

Out put Fi I e = st dout ; 



break; 



continues 
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Listing 9.5. continued 

for ( i =0; i < 50; i ++) 

{ 

/* stdprn is opened in the binary mode, so a CR/LF 
* must be supplied explicitly, using \ n\ r 

*/ 

f pr i n t f ( Ou t p ut F i I e, 

"Li ne %2d of 50 I i nes" 

" being written to user-selected destination by a program. \ n\r", 



/* Use an explicit formfeed to force a page eject if the 
* printer is a laser printer. 

*/ 

f pr i ntf ( Out put Fi I e, "\f " ) ; 
return ( 0) ; 

} 



This program shows the effect of assigning standard file handles to a user- 
specified file. This technique enables you to have one output routine and several 
destinations. This is useful when you want the user to beableto preview a report or 
easily select a secondary printer connected to a communications port. 

Low-Level I/O and File Handles 

All filel/O functionsdescri bed so far perform primarily high-level I/O , and all require 
stream files. (Functionsthat requirestream files receivea fi le * structure pointer.) 

You can also access a file more directly using low-level filel/O techniques. Be- 
fore describing the details of these techniques, however, several important issues 
should be covered. 

A filethat has been opened asastream filecan be read and written to using low- 
level file I/O functions. To get the necessary integer file handle, you must use the 
f i i eno( ) function. 



278 



Disk Files and Other I/O 




A low-level filecan beused with stream functionsby opening it with thef d o p e n ( ) 
function. Be careful not to take a file that has been opened as a stream file, get its file 
handle, then open it a second time with f do pen ( ) . You would then have to close the 
file twice. 

The low-level file I/O functions are shown in Table 9.2. These functions 
generally havea stream filefunction counterpart. 



Table 9.2. Low-level filefunctions. 



Function 


Description 


close() 


Closes the specified file. 


c r e a t ( ) 


Creates a new file. 


d u p( ) 


Creates a new, duplicate file handle. 


d u p2 ( ) 


Creates a new, duplicate file handle and sets the second 




(specified) file handle to the first file. 


eof ( ) 


Tests for an end-of-file. 


1 s e e k ( ) 


Seeks (changes the read/write pointer) to a new place in thefile. 


o pen ( ) 


Opens an existing file. 


r ead ( ) 


Reads an opened file. 


s o pe n ( ) 


Opens a file in shared mode. 


tel 1 ( ) 


Returns the value of the read/write pointer. 


write() 


Writes data to a file that has been opened for output. 



Before you use stream functions with alow-level file, be sure that you open the 
file using the correct stream function. Generally, it is best if you use one type of 
function with any specific file. 

There are several reasonsfor using low-level functions, including thefollowing: 

• Low-level functions do not try to format data, read from a file, or write 
to a file. 

• Low-level file I/O is not buffered. When an I/O statement is executed, 
what is written goes directly to thefile. (This may slow the program's 
execution.) 
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M ost programsbenefit from theuseof stream functions. T hecapability to open, 
read, and write any data object is present in both low-level files and stream files The 
problems caused by buffering, if important, can be circumvented using thefileflush- 
ing routines. 

Standard Low-Level File Handles 

Because stdi n, st dout , stdaux, stder r , and stdpm are stream files, they can be 
referenced using the f i i enoo function. These files can also be used with low-level 
I/O functionsdirectly, however. Thefilehandlenumbersforthestandard stream files 
follows: 

st di n 0 
stdout 1 
s t d e r r 2 
stdaux 3 
s t d p r n 4 

These low-level file numbers should not be used if possible. The f i i eno( i 
function is more portable, especially when a program must run on different systems. 

Console and Port I/O 

M uch of the direct access to the computer's terminal (the screen and keyboard) is 
system dependent. 0 n a PC , you can have any of a number of keyboards, all of which 
havedifferent keys, and different scan codes. Several functions interact moredirectly 
with thekeyboard, and though not all areAN SI standard, they areoften part of many 
C compilers. These functions are shown in Table 9.3. 

You can easilysimulatemostconsolefunctionsbyusingthestream functionsand 
the predefined file handles. A few functions, however, have no equal. This section 
describes the console functions and how to use them. 

Some of the most frequently used direct console functions are the character 
getting functions, get cm ) and getchei ) . The main difference between these two 
functionsisthatgetchi i doesnot echo the character pressed, andgetchei ) doesecho 
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the character. Although the screen functions can be used to read a keypress and echo 
it to the screen, you mustusethegetchi ) function to read a keypress without echoing 
it to the screen. 



Table 9.3. Console I/O functions. 


C nncnlp fiinrtinn 




cget s( ) 


G ets a string from the console. 


c pr i nt f ( ) 


Performs a formatted print to the console. 


c put s ( ) 


W rites a string to the screen. 


c s c a n f ( ) 


Performs a formatted read from the console (key- 




board). 


g et c h ( ) 


G ets a character from the keyboard but does not echo 




the character to the screen. 


getche( ) 


G ets a character from the keyboard and echoes the 




character to the screen. 


kbhi t ( ) 


Returns immediately with the return code indicating 




whether a key has been pressed. Will not wait for a 




keypress. 


put c h ( ) 


W ri tes a ch aracter to th e screen . 


u nget c h ( ) 


Allows one character to be pushed back to the key- 




board. The character put back does not need to be the 




last character read. 0 nly one character may be put 




back. 



Thenext most commonly used function is the kbhi t( ) function, which hasno 
stream function counterpart. T he k b h i t ( ) function enables you to poll the keyboard 
for a keypress. M any business applications have little use for this function. Games, 
however, run in real time, so they must check for user input without stopping 
the action. T he k b h i to function enables a program to do just that. 

Listing 9.6, ARCADE. C, does processing while waiting for keyboard input 
from the user. By a far stretch of the imagination, you could consider this program a 
simple arcade game. 
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Listing 9.6. ARCADE .C. 

/* ARCADE, written 1 99 2 by Peter D. Hipson 

* This is a simple arcade game that uses console I/O. 

* It should be run under DOS on a PC. It also should 

* be compiled with Microsoft C or a compiler that 

* supports kbhitO and getch(). In addition, ANSI . SYS 

* should be loaded before using this program, and the 

* screen size is assumed to be 25 by 80. 
*/ 



tinclude <stdio.h> // Make includes first part of file 

#i n c I u d e <conio.h> // Console I/O functions 

tinclude <string.h> // For string functions 

#i n c I u d e <stdlib.h> // Standard include items 

#include <process.h> // For exit(), etc. 

#i n c I u d e <t i me . h > // To seed random numbers 



/* ANSI . SYS screen control tdefines follow: */ 



#def 


ne 


BOLD 


" \ x 1 B [ 1 m" 


#def 


ne 


NORMAL 


" \ x 1 B [ 0 m" 


#def 


ne 


RED 


" \ x 1 B [ 3 1 m" 


#def 


ne 


BLACK 


" \ x 1 B [ 3 0 m" 


#def 


ne 


GREEN 


" \ x 1 B [ 3 2 m" 



#def i ne CLEAR SCREEN " \ x 1 B [ 2 J " 
#def i ne CLEAREOL " \ x 1 B [ K" 

tdefine MOVE_ CURSOR " \ x 1 B[ %d ; %df " 



#def 


ne 


UP ' \ x 4 8' 


#def 


ne 


DOWN ' \ x 5 0 ' 


#def 


ne 


LEFT ' \ x 4 B' 


#def 


ne 


RIGHT '\x4D' 


#def 


ne 


MAX_ HE 1 GHT 25 


#def 


ne 


MAX_ WIDTH 80 


#def 


ne 


HALF_SECOND ( 



CLOCKS. P E R_ S E C / 2) 
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nt ma i n ( // Define ma i n ( ) and the fact that this 

int argc, // program uses the passed parameters 
char * a r g v [ ] , 
char * e n v p [ ] 
) ; 



9- 



int ma i n ( 

int argc, 
char * a r g v [ ] , 
char * e n v p [ ] 
) 



char c h Ch a r ; 

c I o c k _ t ClockTime; 
cl o c k _ t 01 dCI ockTi me; 



nt 


i ; 














nt 


n Ho r i z o n t a 1 = 0 ; 




/ * Ra n d o mi z e 


for 


real 


g a me 


* 


nt 


nVer t i cal =0; 




/ * Ra n d o mi z e 


for 


real 


game 


* 


nt 


n Mo n ey Ho r i z o n t a 1 


= 10; 


/ * Ra n d o mi z e 


for 


real 


game 


* 


nt 


n Mo n ey Ve r t i c a 1 


= 10; 


/ * Ra n d o mi z e 


for 


real 


game 


* 


nt 


nPos i t i on; 















01 dCI ockTi me = cl ock( ) / HALF SECOND; 
srand( ( unsi gned) ti me( NULL) ) ; 
pr i nt f ( CLEAR SCREEN) ; 

pr i ntf ( MOVE_ CURSOR, n Mo n ey Ve r t i c a I , n Mo n ey Ho r i z o n t a I ) ; 
pri ntf ("$"); 

p r i n t f ( MOVE_ CURSOR, nVertical, n Ho r i z o n t a I ) ; 
pri n t f ( " ? " ) ; 

continues 
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Listing 9.6. continued 

whi I e( 1) 

{ 

if ( kbhi t ( ) ) 

{/* A key has been pressed, so process it as necessary */ 
chChar = get ch() ; 

if (chChar == ( char ) NULL) 

{ 

chChar = getch( ) ; 

pr i ntf ( MOVE_ CURSOR, nVertical, n Ho r i z o n t a I ) ; 
p r i n t f ( " " ) ; 

swi t ch( c hChar ) 

{ 

case DOWN: 

i f ( + + n Ve r t i cal > MAX _ H E I GHT) 

{ 

■■nVertical; 

} 

break; 
case UP: 

if ( - - nVert i cal < 1) 

{ 

+ + n Ve r t i cal ; 

} 

break; 
case Rl GHT: 

if ( + + n Ho r i zont al > MAX_WI DTH) 

{ 

- - nHori zontal ; 

} 

break; 
case LEFT: 

if ( - - n Ho r i z o n t a I < 1 ) 

{ 

+ + n Ho r i zontal ; 

} 

break; 
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d e f a u I t : 
break; 

} 

pr i ntf ( MOVE_ CURSOR, nVertical, nHorizontal); 

if ( nMoneyHori zontal == nHorizontal && 
n Mo n ey Ve r t i c a I == nVertical) 

{ 

p r i n t f ( " \ a " ) ; 

} 

p r i n t f ( " ? " ) ; 

} 

else 

{ 

i f ( chChar == ' \ x lb ' ) 

{/ * Exit on Esc keypress */ 

pr i ntf ( CLEAR_SCREEN) ; 

exi t ( 4) ; 

} 

} 

} 

else 

{/* No key has been pressed. Move the money. */ 
CI ockTi me = clock() / HALFJECOND; 

i f ( CI o c k T i me ! = 01 dCI oc k T i me) 

{ 

01 dCI ockTi me = CI oc k T i me; 

pr i nt f ( MOVE_ CURSOR, n Mo ney Ve r t i c a I , n Mo n ey Ho r i z o n t a I ) ; 
p r i n t f ( " " ) ; / * Erase the mo n e y * / 
i = r a n d ( ) ; 

s wi t c h( i % 4) / * Allow four states */ 
{ 

case 0: 

i f ( ++n Mo n e y Ve r t i cal > MAX_ HEI GHT) 

continues 
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Listing 9.6. continued 

{ 

- - n Mo n e y Ve r t i c a I ; 

} 

break; 
case 1: 

if ( - - n Mo n ey Ve r t i c a I < 1 ) 

{ 

+ + n Mo n e y Ve r t i c a I ; 

} 

break; 
case 2: 

if ( + + nMoneyHor i zont al > MAX_WI DTH) 

{ 

- - n Mo n e y Ho r i z o n t a I ; 

} 

break; 
case 3: 

if ( ■ ■ n Mo n e y Ho r i z o n t a I < 1 ) 

{ 

+ + n Mo n e y Ho r i z o n t a I ; 

} 

break; 

def a u I t : 
break; 

} 

if ( n Mo n ey Ho r i z o n t a I == nHori zontal && 
n Mo n ey Ve r t i c a I == n Ve r t i c a I ) 

{ 

- - nMoneyHor i zontal ; 

- - n Mo n ey Ve r t i c a I ; 

} 

pr i ntf ( MOVE_ CURSOR, n Mo n ey Ve r t i c a I , n Mo n ey Ho r i z o n t a I ) ; 

p r i n t f ( " $ " ) ; / * Display the mo n e y * / 

pr i ntf ( MOVE_ CURSOR, nVertical, n Ho r i z o n t a I ) ; 
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} 

} 

return ( 0) ; 

} 



First the program and thescreen areinitialized. Standard stream I/O statements 
are used becausetheyareeasyto use. Nosensein doing more work than isnecessary! 
Then thescreen iscleared, and thetarget (thedollar agn) is placed at position 10, 10. 
Thechaser (thequestion mark) is then placed at position 0, 0, and the game begins. 

A whi i e loop polls the keyboard. When a key is pressed, kbhi t( ) returnsTRUE, 
allowing the program to read the keypress, as follows: 

if ( kbhi t ( ) ) 

{/* A key has been pressed, so process it as necessary */ 
chChar = get ch( ) ; 

if (chChar == ( c har ) NULL) 
{ 

chChar = getch(); 

I f thefirst call to g et c h ( ) returnszero, an extended key (probably an arrow key) 
has been pressed. If the return is nonzero, an ASCII key has been pressed. The only 
nonextended key that interests us is ESC, which ends the game. 

After a key has been pressed, a new location for thechaser is computed. If the 
chaser has landed on thetarget's position, thespeaker beeps. Try playing the game- 
it's harder than it seems! 

If no key has been pressed, the program checks how long it has been si nee the 
target moved. Every half second, if no key is pressed, the target moves one square in 
a random direction. This time period makes thegamemoreplayable. (Otherwise, on 
a fast CPU , thetarget would be all over thescreen, and you could never hit it.) 

All moves in ARCADE are kept in the bounds of thescreen. In addition, the 
target cannot move to the same position as thechaser— thegameshould never loseby 
its own choice! 
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Direct Port I/O 

Thissection assumes that you are programming on an IBM compatiblePC. Ifyouare 
using another typeof computer, someof thediscussion in thissection may not apply. 

Direct port I/O can be dangerous because the program is interacting with the 
hardware at a basic level. Because thereisno error checking, you can seriously damage 
the information on your hard disk. 




If you are writing software that uses direct port I/O, backup 
your hard disk! 



Direct port I/O issystem dependent, not only on thetypeof computer, but also 
on the computer's configuration. In this section, the assumption is that you are 
programming on an IBM compatiblePC. If you areusing another typeof computer, 
thissection may not apply. 

TheCPU uses the I/O ports to communicate with all the various peripherals, 
such asthecommunication ports, theprinter ports, and thekeyboard. Peripheralsare 
connected to theC PU by i nterfaceards(these may be part of the motherboard). T he 
direct port I/O functions are shown in Table 9.4. 



Table 9.4. Direct I/O functions. 



I/O function Description 



i np{ ) 


1 nputs a byte of data from the specified port 


i n pw( ) 


1 nputs two bytes of data from the specified port 


out p( ) 


0 utputs a byte of data to the specified port 


out p w( ) 


0 utputs two bytes of data to the specified port 
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The return type is always type i nt , so you should use only the first byte in 
functionsthatprocessbyte-sizedata objects. Both output functions return thebyteor 
word that was output. T he input functions return the currently input byte or word. 



The PC Printer Ports 

The PC supports up to three printer ports. The addresses for the printer ports are 
in the B 1 0 S data area, at segment 0040, asfollows: 0040:0008 for L PT 1, 0040:000A 
for LPT2, and 0040:000C for LPT 3. Typical addresses for printer ports are 0x0378 
or 0x03BC . Although there are standard addressesfor theprinter I/O , your program 
could use any I/O address that is defined by thesystem. 

Listing 9.7, PRN PO RT.C, prints to theprinter a single string, followed by a 
form-feed character. (Theform-feed character forceslaser printersto print thepage.) 
Theprogram prints directly, without calling the DOS or the BIOS routines. 

L isting 9. 7. PRNPORT.C. 

/* PRNP0RT, written 1 9 9 2 by Peter D. Hipson 

* This program prints directly to the printer's port. 

* The program should be run under DOS on a PC. If your 

* computer is not PC-compatible, do not run this program. 

* The p r o g r a m s h o u I d also be compiled with Microsoft C. 
*/ 

tinclude <stdio.h> // Make includes first part of file 
# i n c I u d e <conio.h> // Console I/O functions 
tinclude <string.h> // For string functions 
# i n c I u d e <stdlib.h> // Standard include items 
tinclude <process.h> // For exit(), etc. 
tinclude <t i me . h > // To seed random numbers 

tdefine MAKE L ON G ( I ow, high) ( ( I o n g ) ( ( ( u ns i g n ed short i n t ) ( I o w) ) \ 

(((unsigned long i nt ) ( ( unsi gned short int)(high))) << 16))) 
#d ef i n e MAKE L P( s e I , off) ((void far *) MAKEL0NG( ( off ) , (sel))) 

/* Printer port definitions */ 

continues 
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Listing 9.7. continued 



#d e f i 


ne 


Bl 0S_ DATA_ PAGE 


0x0040 


#def i 


ne 


LPT1 




0x0008 


#def i 


ne 


DATA, PORT ( 


n P o r t ) 


#def i 


ne 


STATUS, 


PORT ( 


n Po r t + 


#def i 


ne 


CONTROL 


_ PORT ( 


n P o r t + 


#def i 


ne 


STAT US_ 


NORESP 


0x01 


#def i 


ne 


STATUS, 


UNUSED1 


0x02 


#def i 


n e 


STATUS, 


UNUSED2 


0x04 


#def i 


ne 


STATUS, 


ERROR 


0x08 


#def i 


ne 


STATUS, 


SELECTED 


0x10 


#def i 


n e 


STATUS, 


NOPAPER 


0x20 


#def i 


ne 


STATUS, 


AC K 


0x40 


#d ef i 


n e 


STATUS, 


NOTBUSY 


0x80 


#def i 


ne 


CONTROL 


STROBE 


0x01 


#def i 


ne 


CONTROL 


_ AUTOF E E D 0x02 


#def i 


ne 


CONTROL 


,1 Nl T 


0x04 


#def i 


ne 


CONTROL 


SELECT 


0x08 


#def i 


ne 


CONTROL 


,1 RQ7 


0x10 


#def i 


ne 


CONTROL 


_ UNUS EDI 


0x20 


#def i 


ne 


CONTROL 


_ UNUS ED2 


0x40 


#def i 


ne 


CONTROL 


UNUSED3 


0x80 



/* End printer port definitions. */ 



i n t ma i n ( 

i nt a r g c , 

char * a r g v [ 

char * e n v p [ 



// Define ma i n ( ) and the fact that this 
// program uses the passed parameters 



nt PrintCharacter(char chChar); 
nt PrinterStatus(void); 
n t ma i n ( 

i nt a r g c , 

char * a r g v [ ] , 
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char * e n v p [ ] 



{ 

char szNowl sTheTi me[ ] ={ 

"Now is the time for all good men to come to the aid. . . \ f " > ; 

i n t n St a t us ; 

i nt i ; 



if ( ! Pr i nter St at us( ) ) 

{ 

pri ntf("There was a printer e r r o r ! \ n " ) ; 
exi t ( 4) ; 

} 

for ( i = 0; i < strl en(szNowl sTheTi me) ; i + + ) 
{ 

if ( Pri ntCharacter( szNowl sTheTi me[ i ] ) == 0) 
{ 

pri ntf("\nCouldn't print from ' %s ' \ n " , 
&szNowl sTheTi me[ i ] ) ; 

break; 

} 

} 

return ( 0) ; 

} 

int P r i n t Ch a r a c t e r ( 
char chChar ) 



{ 



int far *pPri ntPort; 
int n Po r t ; 



9- 



continues 
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Listing 9.7. continued 



i nt n S t a t us; 

/* The PC's printer port is at address 0 04 0:0 0 08 

* (for LPT1: ) . If 0 i s stored at that address, 

* a printer port is not installed. 

*/ 

pPrintPort = MAKEL P ( Bl OS_ DATA_ PAGE , LPT1); 
n Po r t = * pPr i nt Por t ; 

if ( nPor t ==0) 

{/* No printer is installed! */ 

p r i n t f ( "No printer installed... WHY?\ n" ) ; 
r et u r n ( 0) ; 

} 

/* Write the data byte to the printer's data lines */ 

out p( DATA_ PORT, chChar); 
/* Next, check to see if the printer is busy. */ 

nStatus = i n p( STATUS_ PORT) ; 

if ( ! ( nSt at us & ST AT US_ N OT B US Y ) ) 

{/* The printer is busy. You should wait and try again */ 
pri ntf( "The printer is b u s y ? \ n " ) ; 
r et u r n ( 0) ; 

} 

/ * Set the strobe line */ 

out p( CONTROL_ PORT, CONTROL_ STROBE | CONTROL I Nl T | CONT ROL _ S E L E CT ) 

/ * Clear the strobe line */ 

out p( CONTROL_ PORT, CONTROL, I Nl T | CONTROL, SELECT) ; 

} 



nt PrinterStatusU 
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i nt far 
i nt 



nPor t ; 



* pPr i nt P o r t ; 



i nt 



nSt at us; 



/* The PC's printer port is at address 0 0 4 0:0 0 0 8 

* (for LPT1: ) . If 0 is stored at that address, 

* a printer port is not installed. 

*/ 

pPrintPort = MA K E L P ( B I OS _ DAT A_ P A G E , LPT1); 
nPort = *pPri ntPort; 

if ( nPor t ==0) 

{/* No printer is installed! */ 

pri ntf ( "No pri nter i nstal I ed. . . WHY?\n") ; 
r et u r n( 0 ) ; 

} 

pri ntf( "Pri nter vector = %l p Printer port %4 . 4 X \ n " , 
p P r i n t Po r t , 
n Po r t ) ; 

nStatus = i np( DATA_ PORT) ; 

pri ntf ("DATA port's contents %2 . 2 X (last character that was 
printed). \n", 

nSt a t us ) ; 

nSt at us = i n p( STATUS_ PORT) ; 

if ( ! ( nSt at us & S T AT U S _ NORES P ) ) 
{ 

pri ntf("The printer did not respond. \n"); 

} 

else 

{ 



continues 
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Listing 9.7. continued 

pri ntf( "The printer is responding. \ n " ) ; 

if ( ! ( nSt at us & STAT US_ ERROR) ) 

pri ntf( "The printer is signaling an error. \n"); 

else 

pri ntf( "The printer is signaling no errors. \n"); 

if ( nStat us & STATUS_ SEL ECTED) 

pri ntf( "The printer is currently selected. \n"); 

else 

pri ntf( "The printer is not selected. \n"); 

if ( nStat us & STATUS_ NOPAPE R) 

pri ntf( "The printer is out of p a p e r . \ n " ) ; 

else 

pri ntf( "The printer has paper. \ n " ) ; 

if ( nStat us & STATUS_ ACK) 

pri ntf( "The printer ACK line is s e t . \ n " ) ; 

else 

pri ntf( "The printer ACK line is cleared. \ n " ) ; 
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if ( nSt at us & STATUS. NOTBUSY) 

{ 

pri ntf("The printer is not busy. \ n " ) ; 

} 

else 

{ 

pri ntf("The printer is currently busy. \ n " ) ; 

} 

r et u r n ( 1 ) ; 

} 



The PRN PO RT.C program shows how easy it is to print to a printer port 
using a high-level language such asC. Admittedly, thisprogram cannot beused in its 
current state— thecharacter print routines require moreerror checking and recovery. 
These improvements, however, would not be difficult to implement. 

I have written custom printer drivers for the PC in C . W hy? I n one case, the 
printer (a special graphics printer with a high-speed interface) needed special timing 
and control signals, even though it used a C entronicstypeof connector and thesame 
printer pins as other compatible printers 

A second useof theprinter port isonethat I think is more interesting than sim- 
ply printing. In most PCs, theprinter port is a bidirectional I/O port (it can both 
output data and read data) and as such can beused to communicate with all types of 
external devices. 

A third usefor custom driversisfor 1 10 boardsthat arenot intended to beprinter 
ports but have a similar structure. T hese boards are used for control and for special 
devices. It is not unusual for a special board to be used for graphic tablets (which 
might also use a serial port) or most tape drives, all of which need drivers. 

You must write the driver in assembler (you can use in-line assembly if your 
compiler supports it) for thebest control and performance. A C language driver isad- 
equate, however, for initial development and for drivers with noncritical timing 
requirements. 
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The PC Communications Ports 

T heserial communicationsportsaremorecomplexthan theprinter ports. First, they 
require more initialization because the speed (baud rate) and theformatof the char- 
acters (number of bits) must beset. To makethings easy, I haveD OS initialized my 
AUTO EXEC. BAT file) all the communications ports to a known state. 

Following are the addresses used by the PC communications ports. When a 
communications port is accessed, the first address used is referred to as the I/O base 
address. The communications port I/O address starts at 0x03 F 8 or 0x02F8 (CO M 1 
and C 0 M 2) in most PCs. All ad dresses are accessed using input and output functions, 
either in C or assembler. 

In the following discussion, the CO M 1 base I/O address of 0x3 F 8 is used. To 
access C 0 M 2, you must use theCO M 2 base I/O address of 0x2 F 8. To access a port 
other than CO M 1 or CO M 2, you must know the port's base I/O address. The 
addresses for CO M 1 through COM4 are stored in the BIOS data page as follows: 

COM 1 0000:0400 

COM 2 0000:0402 

COM 3 0000:0404 

COM 4 0000:0406 

TheUART (Universal Asynchronous Receiver/Transmitter) is the part of the 
communications port that convertsa byte of data to a serial data stream. T he U ART 
in the PC's communications port has eight separate addresses. The following para- 
graphsand Table9.5 describe each of these addresses. 

Table 9.5. The serial board'sl/O port usage. 

Name in 

Name Address Description SENDCOMM.C Bits 

Receive I/O base C haracters received RBR_PORT0-7 Eight bitsof 
buffer address may be retrieved received data 

+ 0 from this I/O 

address. LCR_PORT 

bit 80 must be clear. 
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9- 



Name 


Address 


Description 


Name in 
SENDCOMM.C 


Bits 


Divisor 
register 
(LSB) 


I/O base 
address 
+ 0 


U sed to set the baud 
rate, which is deter- 
mined using a 16-bit 
divisor. 

LCR_PORT bit 
80 must beset. 


D LL_PO RT 0-7 


Divisor's LSB 
(eight bits) 


Transmit 
buffer 


I/O base 
address 
+ 0 


Characters to be 
transmitted are 
output to this I/O 
address. LCR_PORT 
bit 80 must be clear. 


TH R_PO RT 0-7 


Eight bits of 
data to be 
transmitted 


1 nterrupt 

enable 

register 


I/O base 
address 
+ 1 


Enables the con- 
ditions that cause the 
UART to generate an 
interrupt to be gener- 
ated. When a specified 
bit is set and the con- 
dition occurs, an inter- 
rupt is generated. 


IER_PORT 01 


Received data 
available. A 
character has 
been received. 



02 



04 



08 



10 



Transmit 
holding register 
is empty. The 
character that 
was being sent 
has completed. 
A new character 
can now be 
sent. 

Receive line status. 
The receive line has 
changed. 

MODEM status. 
T he modem status 
line has changed. 

N ot used 



continues 
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Table 9.5. continued 

Name in 

Name Address Description SENDCOMM.C Bits 









20 


N nt i icpH 

1 M U L U XU 








40 


N nt ucprt 








80 


M nt w^pci 

1 M UL U JCU 


U 1 VlbUI 


l/D hac» 
i/u Udbc 


1 1 coH f"n cof f"ho hai iH 
U DCU LU DCL Lllc UdUU 


DIM PORTA- 7 
u l i v i ruiii u / 


n iwicnr'c M 

U 1 VI bUI j rl JL 


register 


address 


rate, which is deter- 




(eight bits) 


(MSB) 


+ 1 


mined using a 16-bit 










divisor LCR PORT 










bit 80 must beset. 






Interrupt 


I/O base 


Tells the program 


IIR_PORT 01 


If clear, an 


identifier 


address 


what condition caused 




interrupt is 


register 


+ Z 


the interrupt. 




pending 








02 


Interrupt ID, 








04 


Interrupt ID, 








08 


Not used 








10 


Not used 








20 


Not used 








40 


Not used 








80 


Not used 


Line 


I/O base 


Controls the format 


LCR_PORT 01 


Word length, 


control 


address 


of the characters be- 




bitO 


register 


+ 3 


ing transmitted, in- 







eluding the number 
of bits, the number of 
stop bits, and the 
parity. The divisor 
latch (see the divi- 
sor register) is also 
located at this 
address, bit 80. 



02 Word length, bit 1 

04 Stop bits (clear = 1, 

set =2) 

08 Parity enable 
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Name Address Description 



Name in 
SENDCOMM.C 



Bits 



MODEM 

control 

register 



I/O base 
address 
+ 4 



mes. 



Line status I/O base Status of various 
register address + 5 parameters. 



10 


Even Daritv 


20 


Stick parity 


40 


Set break 


oU 


Enable divisor 




latches 


m L K rUKI U 1 


U 1 K 


uz 


DT C 

r\ i j 


U4 


n 1 1 t i 

UU 1 1 


Uo 


n 1 1 t i 

U U 1 z 


1U 


1 r\r\r\ Karl/ - 
LUUp UdLK. 


zU 


N ot u sed 




IM UL UbtJJ 


80 


N ot used 


i pn rt m 


n ata hac hoon 
u alo I lab Uca I 




receiveu. 


02 


Overrun error. The 




previous character 




IctclvcU Web MUL 




IcdU Uy Lllc 




computer and has 




been overwritten 




by the following 




character. 


04 


Parity error. There 




was a parity error 




in the character 




being received. 


08 


Framing error. The 




start/stop bits could 




not be detected 




correctly. 


10 


Break interrupt. A 




break has been 




detected. 


20 


Transmit buffer 




empty 



continues 
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Table 9.5. continued 

Name in 



Name Address Description SENDCOMM.C Bits 









40 


Transmit shift 
register is empty. 
The output shift 
register is currently 
empty. 








80 


Not used 


MODEM 

status 

register 


I/O base 
address + 6 


Status of MODEM 
signal lines. 


MSR PORT 01 

02 

04 

08 

10 

20 

40 

80 


DCTS 

DDSR 

TERI 

DDCD 

CTS 

DSR 

Rl (ring indicator) 
DCD 



The receive buffer is located at base address +0. The functionality of base ad- 
dress + 0 is controlled by bit 0x80 of LCR_PORT. If this bit is clear (zero), base 
address +0 is used as the receive buffer. 

The baud rate divisor register (LSB) is also located at base address +0. The 
functionality of base address + 0 is controlled by bit 0x80 of LC R_PO RT. If this 
bit is set, base address + 0 is used as the divisor register (LSB). 

The transmit buffer is located at base address + 0. The functionality of base 
address + 1 is controlled by bit 0x80 of LCR_PORT. If this bit is clear (zero), base 
address + 1 is used as the interrupt enable register. 

The baud rate divisor register (M SB) is also located at base address + 1. The 
functionality of base address + 1 iscontrolled by bit 0x80 of LCR_PORT. If thisbit 
is set, base address + 1 is used as the divisor register (M SB). 

T heinterrupt enableregister islocated at base address +1. 0 nly thefirst four bits 
are used in this register. 

T heinterrupt identifier register is located at base address +2. 1 1 is used to tell the 
program what condition caused the interrupt. 
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Thelinecontrol register is located at base address +3. This register controls the 
character format and the mapping of the divisor latch ( see offset -K) and +1). 

The modem control register is located at base address +4. This register is used 
to control the port's I/O connector control signals. These signals are then used to 
control the modem (or whatever else is connected to the port). 

The line status register is located at base address +5. It is used to pass to the 
program information regarding thestatus of theU ART and thedata being received. 

T heM 0 D E M status regi ster i si ocated at baseaddress +6. T heprogram usesthis 
register to determine the status of the device connected to the port. 

N otehowtheD LL and D LM registers(thespeed registers) havethesameaddress 
astheRBR and IER registers. This is accomplished with the divisor latch enable 
bit (0x80) of the LC R register. I f this bit is set, these registers are used for the speed 
divisor. If this bit is cleared, these registers serve their other purpose. 

A communications program can rely on theD 0 S M 0 D E command setting the 
communications port parameters, or the program can set the parameters itself. Each 
of the port's registers may be read (except transmitted data), modified, and written 
back. This process of reading, modifying, and writing a register isall that is required 
to initialize the serial port. 

Listing 9.8, SEN DCO M M .C, sends a single string, followed by a lf/cr 
character pair, to COM 1:. Before you run SEN DCO M M .C, COM 1: must be in- 
itialized with the D 0 S M 0 D E command. 

L isting 9. 8. SENDCOMM.C. 

/* SENDCOMM, written 1 9 9 2 by Peter D. Hipson 

* This program outputs to the serial port. You should 

* run this program under DOS on a PC. If your computer 

* is not a PC- c o mpa t i b I e , DO NOT RUN this program. Also, 

* the p r o g r a m s h o u I d be compiled with Microsoft C. 
*/ 



finclude <stdio.h> // Make includes first part of file 
tinclude <conio.h> // Console I/O functions 
# i n c I u d e <string.h> // For string functions 

continues 
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Listing 9.8. continued 



#i n c I u d e <stdlib.h> // Standard include items 

#i n c I u d e <process.h> // For exit(), etc. 

#i n c I u d e <t i me . h > // To seed random numbers 

#define MAKE L ONG ( I ow, high) ( ( I on g ) ( ( ( u n s i g n ed short i n t ) ( I o w) ) \ 

(((unsigned long i n t ) ( ( u n s i g n ed short int)(high))) << 16))) 
#define MAKE L P ( s e I , off) ((void far*) MA KELONG( ( off ) , (sel))) 



/* Co mm port definitions */ 



#def i ne Bl OS_ DATA_ PAGE 


0x0040 


#def i ne COM1 


0x0000 


/* Receive a character port (read only) */ 


#def i ne RBR_ PORT 


( nPort ) 


/* Send (trans mi t) a character 


port (write 


#def i ne THR_ PORT 


( nPort ) 


/* Interrupt enable register */ 




#def i ne 1 ER_ PORT 


( nPort + 1) 


#def i ne RECEI V E D_ DAT A_ A V A 1 LABLE 


0x01 


#def i ne TRANSMI T_ HOL D_ EMPTY 


0x02 


#def i ne RECI EVE R_ L 1 NE_ STATUS 


0x04 


#def i ne MODE M_ S TAT U S 


0x08 


/ * Ot her bits undef i ned */ 




/* Interrupt identify register 


(read only) 


#def i ne II R_ PORT 


( nPort + 2) 


#def i ne 1 NTERUPTPENDI N G _ 0 


0x01 


#def i ne 1 NTERUPTJ D_ B 1 T_l 


0x02 


#def i ne 1 NTERUPTJ D_ B 1 T_2 


0x04 


/ * Ot her bits undef i ned */ 





/* L 


ne 


control register */ 
















#def 


ne 


LCR_ PORT 


( n Po r t 


+ 


3) 










#def 


ne 


WORD_LENGTH_SELECT_l 


0x01 


* 


00 


= 5 bits, 


01 


= 6 bits 


* 


#def 


ne 


WO RDLENGTHSELECT2 


0x02 


* 


10 


= 7 bits, 


11 


= 8 bits 


* 


#def 


ne 


NUMBER_STOP_ Bl TS 


0x04 


* 


0 


= 1 stop, 


1 = 


2 stop 


* 


#def 


ne 


PARI TY ENABL E 


0x08 














#def 


ne 


EVEN PARI TY SELECT 


0x10 
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9- 



#def 
#d ef 
#d ef 

/ * Ot her bits undefined */ 



ne STI C K_ P A Rl TY 0x20 
ne S E T _ BREAK 0x40 

ne DIVISOR LATCH BIT 0x80 /* For DLL and DLH access */ 



/* Modem control register */ 



#d ef 


ne 


MCR.PORT 


( nPo r t 


#d ef 


ne 


DTR 


0x01 


#d ef 


ne 


RTS 


0x02 


#d ef 


ne 


OUT_l 


0x04 


#d ef 


ne 


OUT_ 2 


0x08 


#d ef 


ne 


LOOP 


0x10 



/ * Ot her bits undefined */ 



/* L 


ne 


status register */ 




#d ef 


n e 


L S R_ PORT 


( nPo r t 


#d ef 


ne 


DATA. READY 


0x01 


#d ef 


ne 


OVERRUN. ERROR 


0x02 


#d ef 


ne 


PARI TY_ E RROR 


0x04 


#d ef 


ne 


F RAMI NG_ ERROR 


0x08 


#d ef 


ne 


BREAKJ NTERUPT 


0x10 


#d ef 


ne 


TRANSHOLDI NG_ REGI STER 


0x20 


#d ef 


ne 


TRANS. SHI F T_ REGI STER 


0x40 


/ * Ot her 


bits undefined */ 





/ * Modem st at us register */ 



#d ef 


ne 


MSR.PORT 


( nPo r t 


#d ef 


ne 


DCTS 


0x01 


#d ef 


ne 


DDSR 


0x02 


#d ef 


ne 


TERI 


0x04 


#d ef 


ne 


DDCD 


0x08 


#d ef 


ne 


CTS 


0x10 


#d ef 


ne 


DSR 


0x20 


#d ef 


ne 


Rl 


0x40 


#d ef 


ne 


DCD 


0x80 



/* Divisor latch least significant (sets speed) */ 
#def i ne DL L_ PORT ( nPort + 0) 

/ * Bits 0 - 7 */ 



continues 
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Listing 9.8. continued 



/ * D 


v i 


5 o r latch mo s t 


significant (sets 


speed) * 


#d ef 


ne 


DL M_ 


PORT 


( n P o r t 


+ 1) 


/* B 


ts 


8 - 


15 */ 






#d ef 


ne 


BAUD 


_50 


0x0900 




#d ef 


ne 


BAUD 


_75 


0x0600 




#d ef 


ne 


BAUD 


110 


0x0417 




#d ef 


ne 


BAUD 


134 


0x0359 




#d ef 


ne 


BAUD 


150 


0x0300 




#def 


ne 


BAUD 


300 


0x0180 




#d ef 


ne 


BAUD 


600 


OxOOCO 




#d ef 


ne 


BAUD 


1200 


0x0060 




#def 


ne 


BAUD 


1800 


0x0040 




#def 


ne 


BAUD 


. 2 0 0 0 


0 x 0 0 3 A 




#d ef 


n e 


BAUD 


2 4 0 0 


0x0030 




#def 


ne 


BAUD 


3 6 0 0 


0x0020 




#def 


ne 


BAUD 


4 8 0 0 


0x0018 




#def 


ne 


BAUD 


7 2 0 0 


0x0010 




#def 


ne 


BAUD 


9 6 0 0 


OxOOOC 




#def 


ne 


BAUD 


1 4 4 0 0 


0x0008 




#def 


ne 


BAUD 


1 9 2 0 0 


0x0006 




#def 


ne 


BAUD 


3 8 4 0 0 


0x0003 




#def 


ne 


BAUD 


5 6 0 0 0 


0x0002 




#def 


ne 


BAUD 


112000 


0x0001 





/* End serial port definitions */ 



n t ma i n ( 

i nt a r g c , 

char * a r g v [ ] , 

char * e n v p [ ] 



// Define ma i n ( ) and the fact that this 
// program uses the passed parameters 



nt Seri al Character( char chChar); 
nt Seri al St at us( v o i d) ; 
n t ma i n ( 

i nt a r g c , 

char * a r g v [ ] , 
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char 



*envp[ ] 



char szNowl sTheTi me[ ] ={ 

"Now is the time for all good men to come to the a i d . . . \ n\ r " } ; 



if (! Ser i al Status! ) ) 

{ 

pri ntf("There was a serial e r r o r ! \ n " ) ; 
exi t ( 4) ; 

} 

for ( i = 0; i < strl en(szNowl sTheTi me) ; i + + ) 



if ( Ser i a I Ch a r a c t e r ( s z No wl s TheT i me [ i ] ) == 0) 



pri ntf("\nCouldn't send f r o m c h a r a c t e r ' %s ' \ n " , 
&szNowl sTheTi me[ i ] ) ; 



i nt 



nSt a t us ; 



i nt 



break; 



return 



(0); 



i nt 



Serial Character! 
char chChar ) 



i n t far 



* pSe r i al Port; 



i nt 



nPor t ; 



continues 
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Listing 9.8. continued 



i nt nSt at us ; 

/* The PC's serial port is at address 0 0 40:0 0 0 0 

* (for COM1 : ) . If a zero is stored at that address, 

* a serial port is not installed. 

*/ 

pSerialPort = MAKE L P ( Bl OS_ DATA_ PAGE , COM1); 
nPort = *pSerial Port; 



if ( nPor t ==0) 

{/* No serial port is installed! */ 

pr i ntf ( " No serial installed... WHY?\ n" ) ; 
r et u r n ( 0) ; 

} 



/* Write the data byte to the serial port's data lines. 

* The program must wait until the last character 

* has been sent because the simple hardware does not 

* have a queue. 

*/ 



nSt at us = i np( L S R_ PORT) ; 



while (MnStatus & TRANSHOLDI N G _ R E G I STER) ) 
{/* Simply get the status again, which wastes time */ 
nStat us = i np( L S R_ PORT) ; 

} 



out p( THR_ PORT, chChar); 



r et u r n ( 1 ) ; 



nt Ser i a I St at us I 
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i nt far 
i nt 



nPor t ; 



* pSe r i al Port; 



i nt 



nSt at us; 



/* The PC's serial port is at address 00 4 0:00 0 0 

* (for COM1:). If a zero is stored at that address, 

* a serial port is not installed. 

*/ 

pSerialPort = MAKE L P ( Bl OS_ DATA_ PAGE , COM1); 
nPort = *pSeri al Port; 

if ( nPor t ==0) 

{/* No serial port is installed! */ 

pri ntf( "No serial board installed... Wh y ? \ n " ) ; 
r e t u r n ( 0 ) ; 

} 

pri ntf( "Seri al vector = %l p Serial port %4 . 4 X \ n " , 
pSer i al Port, 
n Po r t ) ; 

nStatus = i np( MCR_PORT) ; 

pri ntf ( " MCR_ PORT returned %2.2X\n", nStatus); 
if (nStatus & DTP,) 

pr i n t f ( " DTR is high. \ n" ) ; 



I s e 



pr i n t f ( " DTR is low. \ n" ) ; 



f (nStatus & RTS) 



pr i ntf ( " RTS is high. \ n") ; 



continues 
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Listing 9.8. continued 



else 
{ 

pri ntf( "RTS is low. \ n" ) ; 

} 

nSt at us = I n p ( I E R_ PORT) ; 

pri n t f ( " I E R_ PORT returned %2.2X\n", nStatus) 
nSt at us = i np( I I R_ PORT) ; 

pri ntf("l I R PORT returned %2.2X\n", nStatus) 
nSt at us = i n p ( L C R_ PORT) ; 

pri ntf ( " L C R_ P ORT returned %2.2X\n", nStatus) 
nStatus = i np( MCR_ PORT) ; 

pri ntf ( " MCR_ PORT returned %2.2X\n", nStatus) 
nStatus = i n p ( L S R_ PORT) ; 

pri ntf ( " L S R_ P ORT returned %2 . 2X\ n" , nStatus) 
nStatus = i np( MS R_ PORT) ; 

pri ntf ( " MS R_ PORT returned %2 . 2X\ n" , nStatus) 
r et u r n ( 1 ) ; 



SEN DCOM M is simple, in that it only displays thestatus of the registers, then 
sends the string. Following is the code that sends the characters: 

nStatus = i np( L S R_ PORT) ; 

while ( ! ( nStatus & TRANSHOLDI NGREGI STER) ) 

{/* Simply get the status again, which wastes time */ 
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nSt at us = i n p ( L S R_ PORT) ; 

} 

out p( THR_ PORT, chChar); 

First, the program gets the port's status. If the trans_ hol di ng regi ster bit is 
clear, thecharacter can be sent. If the bit is set, theprogram waitsforthehardwareto 
send the current character, at which point the bit is cleared. 

After the trans holdi ng regi ster is clear, the program sends the character 
using a call to o u t p ( i . T he hardware handles the serial transmission of the character 
in a serial format. 

SENDCOM M .C is a simple character sending program. Receiving a character 
is just as easy. Listing 9.9, R E AD C 0 M M .C, gets a character from the serial port, 
sends it back (echoes the character), and displays it on the terminal's screen. 

L isting 9.9. READCOMM.C. 

/* READCOMM, written 1 9 9 2 by Peter D. Hipson 

* This program reads characters from the serial port. 

* You should run this program under DOS on a PC. If 

* your computer is not a PC- c o mpat i b I e , DO NOT RUN 

* this program. Also, the program should be compiled 

* wi t h Mi c r osof t C. 
*/ 

tinclude <stdio.h> // Make includes first part of file 
tinclude <conio.h> // Console I/O functions 
tinclude <string.h> // For string functions 
tinclude <stdlib.h> // Standard include items 
# i n c I u d e <process.h> // For exit(), etc. 
tinclude <t i me . h > // To seed random numbers 

tdefine MAKE L ONG ( I ow, high) ( ( I ong) ( ( ( u ns i g ned short i n t ) ( I o w) ) \ 

(((unsigned long i nt ) ( ( unsi gned short int)(high))) << 16))) 
#d ef i n e MAKE L P( s e I , off) ( ( v o i d _f a r * ) MAKEL ONG( ( of f ) , (sel))) 

/* Co mm port definitions */ 

continues 



309 



Part 1 1 • Managing Data in C 



Listing 9.9. continued 

#def i ne Bl OS_ DATA_ PAGE 0 x 0 0 40 

#def i ne COM1 0 x 0 0 00 

/* Receive a character port (read only) */ 



#def i ne RBR_ PORT 


( nPort ) 












/* Send (trans mi t) a character 


port ( wr 


i t e only) * / 








#def i ne THR_ PORT 


( nPort ) 












/* Interrupt enable register */ 














#def i ne 1 ER_ PORT 


( n Po r t 


+ 


1) 








#def i ne RECEI VE D_ DATA_ AVAI LABLE 


0x01 












#def i ne T RAN S Ml T_ HOL D_ EMPTY 


0x02 












#def i ne RECI EVE R_ L 1 NE_STATUS 


0x04 












#def i ne MODE M_ STATUS 


0x08 












/ * Ot her bits undef i ned */ 














/* Interrupt identify register 


(read only) */ 








#def i ne II R_ PORT 


( n Po r t 


+ 


2) 








#def i ne 1 NTERUPT PENDI NG_ 0 


0x01 












#def i ne 1 NTERUPTJ D_ B 1 T_l 


0x02 












#def i ne 1 NTERUPTJ D_ B 1 T_2 


0x04 












/ * Ot her bits undef i ned */ 














/* Line control register */ 














#def i ne LCR_ PORT 


( nPort 


+ 


3) 








#def i ne WORD_ LENGTH_ SEL E CT_ 1 


0x01 / 


* 


00 = 5 bits, 


01 


= 6 bits 


* 


#define WORD LENGTH SELECT 2 


0x02 / 


* 


10 = 7 bits, 


1 1 


= 8 bits 


* 


#def i ne NUMBER_STOP_ Bl TS 


0x04 / 


* 


0 = 1 stop, 


1 


= 2 stop 


* 


#def i ne PARI TY ENABL E 


0x08 












#def i ne E V E N _ PARI TY SELECT 


0x10 












#def i ne STI C K_ PARI TY 


0x20 












#def i ne SET_ BREAK 


0x40 












#def i ne Dl VI SOR_LATCH_BI T 


0x80 / 


* 


For DLL and 


DL H 


access * 




/ * Ot her bits undef i ned */ 














/* Modem control register */ 














#def i ne MCR_ PORT 


( n Po r t 


+ 


4) 








#def i ne DTR 


0x01 












#def i ne RTS 


0x02 












#def i ne OUT 1 


0x04 
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#d ef i n e 


OUT_ 2 


0x08 


# d e f i n e 


LOOP 


0x10 


/ * Ot her 


bits undefined */ 




/ * Line 


status register */ 




# d e f i n e 


L S R_ P ORT 


( nPort +5) 


#d ef i n e 


DATA_ READY 


0x01 


#d ef i n e 


OVERRUN_ ERROR 


0x02 


#d ef i n e 


PARI TY_ E RROR 


0x04 


#d ef i n e 


F RAMI NG_ ERROR 


0x08 


#d ef i n e 


BREAKJ NTERUPT 


0x10 


#d ef i n e 


TRANS. HOLDI NG_ REGI STER 


0x20 


#d ef i n e 


TRANS SHIFT REGI STER 


0x40 



9- 



/ * Ot her bits undefined */ 
/ * Modem st at us register */ 



#d ef 


ne 


MSR.PORT 


( nPo r t 


#def 


ne 


DCTS 


0x01 


#def 


ne 


DDSR 


0x02 


#def 


ne 


TERI 


0x04 


#def 


ne 


DDCD 


0x08 


#def 


n e 


CTS 


0x10 


#def 


ne 


DSR 


0x20 


#def 


ne 


Rl 


0x40 


#def 


ne 


DCD 


0x80 



+ 6) 



/* D 


v i 


sor latch 


least significant (sets speed) * 


#d ef 


n e 


DL L_ PORT 


( nPo r t +0) 


/* B 


t s 


0 ■ 7 */ 




/* D 


v i 


sor latch 


mo st significant (sets speed) */ 


#d ef 


ne 


DL M_ PORT 


( nPort +1) 


/* B 


t s 


8 - 15 * 


/ 


/* B 


t s 


def i ned 


as OxMMLL. MM i s DL M. LL is DLL * 


#d ef 


n e 


BAUD_ 50 


0x0900 


#d ef 


ne 


BAUD_ 7 5 


0x0600 


#d ef 


ne 


BAUD_ 1 1 0 


0x0417 


#d ef 


n e 


BAUD_ 1 3 4 


0x0359 


#def 


ne 


BAUD 150 


0x0300 



continues 
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Listing 9.9. continued 



#d e f 


ne 


BAUD_ 


300 


0x0180 


#d e f 


ne 


BAUD_ 


600 


OxOOCO 


#d e f 


ne 


BAUD_ 


1200 


0x0060 


#d e f 


n e 


BAUD_ 


1800 


0x0040 


#d e f 


ne 


BAUD_ 


2 0 0 0 


0x003A 


#d ef 


n e 


BAUD 


2 4 0 0 


0x0030 

U A U U J U 


#d e f 


ne 


BAUD_ 


3 6 0 0 


0x0020 


#d e f 


ne 


B AUD_ 


4 8 0 0 


0x0018 


#d e f 


ne 


BAUD_ 


7 2 0 0 


0x0010 


#d e f 


ne 


BAUD_ 


9 6 0 0 


OxOOOC 


#d e f 


ne 


BAUD_ 


1 4 4 0 0 


0x0008 


#d e f 


ne 


BAUD_ 


1 9 2 0 0 


0x0006 


#d e f 


ne 


BAUD_ 


3 8 4 0 0 


0x0003 


#d e f 


ne 


BAUD_ 


5 6 0 0 0 


0x0002 


#d e f 


ne 


BAUD 


112000 


0x0001 



/* End serial port definitions */ 



nt main( // Define ma i n ( ) and the fact that 

int argc, // this program uses the passed parameters 
char * a r g v [ ] , 
char * e n v p [ ] 
) ; 

nt Get S e r i a I Ch a r a c t er ( c h a r *chChar); 
nt Ser i al St at us( voi d) ; 



int ma i n ( 

int argc, 
char * a r g v [ ] , 
char * e n v p [ ] 
) 



{ 



char c h Ch a r ; 

int n S t a t us; 

int i ; 
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if (! Ser i al Status! ) ) 

{ 

pri ntf("There was a serial e r r o r ! \ n " ) ; 
exi t ( 4) ; 

} 

wh i I e ( 1 ) 

{ 

if ( kbhi t ( ) ) 

{/* Discard the keypress and end */ 
( vo i d ) get c h ( ) ; 
break; 

} 

if ( GetSeri al Character! &c hC h a r ) ) 

{/* Print the received character, and get another */ 
pri n t f ( " %c " , c h C h a r ) ; 

} 

} 

return ( 0) ; 

} 

i nt Get Ser i a I Cha r ac t er ( 
char * c h C h a r ) 



int far *pSeri al Port; 
i n t n Po r t ; 

int n St a t us ; 

/* The PC's serial port is at address 00 4 0:00 0 0 

* (for COM1:). If a zero is stored at that address, 

* a serial port is not installed. 

*/ 

pSerialPort = MAKE L P ( Bl OS_ DATA_ PAGE , COM1); 
nPort = *pSeri al Port; 

continues 



313 



Part 1 1 • Managing Data in C 



Listing 9.9. continued 

if ( nPort ==0) 

{/* No serial is installed! */ 

pri ntf( "No serial installed. ..Why?\n"); 
r et u r n ( 0) ; 

} 

/* To read a character, the DATA_READY signal must be set 

* (see the previous defines). This bit is in L S R_ PORT. 

* If DATA_ READY is set, the program reads a character 

* and returns TRUE. 

*/ 

nSt at us = i np( L S R_ PORT) ; 

if ( nStat us & DATA_ READY ) 
{/* A character has been received. */ 
*chChar = i n p ( RBR_ PORT) ; 

/* Echo the data byte back to the sender. The program 

* must wait until the last character has been sent 

* because the simple hardware does not have a gueue. 

*/ 

nStat us = i n p ( L S R_ PORT) ; 

while (MnStatus & TRANSHOLDI NGREGI STER) ) 
{/* Simply get the status again, which wastes time */ 
nStatus = i np( LS R_ PORT) ; 

} 

outp(THR_PORT, *chChar); 
r et u r n ( 1 ) ; 

} 

r et u r n ( 0 ) ; 

} 



i nt Ser i al St at us ( ) 
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{ 

i nt far *pSeri al Port; 

i nt nPor t ; 

i nt nTempSt at us; 

i n t n St a t us ; 

/* The PC's serial port is at address 00 4 0:00 0 0 

* (for COM1:). If a zero is stored at that address, 

* a serial port is not installed. 

*/ 



pSerialPort = MAKE L P ( Bl OS_ DATA_ PAGE , COM1); 
nPort = *pSeri al Port; 

if ( nPort ==0) 

{/* No serial is installed! */ 

pri ntf( "No serial board installed. . . Wh y ? \ n " ) ; 
r et u r n( 0 ) ; 

} 

pri ntf( "Seri al vector = %l p Serial port %4 . 4 X \ n " , 
pSer i al Port, 
n Po r t ) ; 

nStatus = i np( MCR_ PORT) ; 

pri ntf ( " MCR_ PORT returned %2.2X\n", nStatus); 

if (nStatus & DTP,) 

{ 

pr i n t f ( " DTR is high. \ n" ) ; 

} 

else 

{ 

pr i n t f ( " DTR is low. \ n" ) ; 

} 

continues 
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Listing 9.9. continued 



if ( nStat us & RTS) 

{ 

pri ntf( "RTS is high. \ n") ; 

} 

else 

{ 

pri ntf( "RTS is low. \ n" ) ; 

} 

nSt at us = i np( I E R_ PORT) ; 

pri n t f ( " I E R_ PORT returned %2.2X\n", nStatus); 
nSt at us = i np( I I R_ PORT) ; 

pri ntf("l I R PORT returned %2.2X\n", nStatus); 
nSt at us = i np( L C R_ PORT) ; 

pri ntf ("LCR_PORT returned %2.2X\n", nStatus); 
nStatus = i n p ( MCR_ PORT) ; 

pri ntf ( " MCR_ PORT returned %2 . 2 X \ n " , nStatus); 
nStatus = i n p ( L S R_ PORT) ; 

pri ntf ( " L S R_ P ORT returned %2.2X\n", nStatus); 
nStatus = i n p ( MS R_ PORT) ; 

pri ntf ( " MSR_ PORT returned %2.2X\n", nStatus); 
nTempStat us = i n p ( L C R_ PORT) ; 

out p( L CR_ P ORT , nTempSt at us | Dl VI SOR_ LATCH_ Bl T) 
nStatus = i n p ( DL M_ PORT) ; 

pri ntf ( " DL M_ PORT returned %2 . 2 X \ n " , nStatus); 
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nStatus = i np( DL L_ PORT) ; 

pri ntf( "DLL _ PORT returned %2.2X\n", nStatus); 
out p( LCR PORT, nTempSt at us ) ; 
r et u r n ( 1 ) ; 

} 



READ CO M M .C uses a simple loop to read the characters. The part of the 
program that does the reading is shown in bold in the following code fragment. 
Theother parts of the code fragment are the echo code. Echoing received characters 
is optional and is usually controlled by the user. 

nStatus = i np( LS R_ PORT) ; 

i f ( nStatus & DATA_ READY ) 
{/* A character has been received. */ 
*chChar = i np( RBR_ PORT) ; 

/* Echo the data byte to the sender. The program 

* must wait until the last character has been sent 

* because the simple hardware does not have a queue. 

*/ 

nStatus = i np( L S R_ PORT) ; 

while ( ! ( nStatus & TRANSHOLDI NGREGISTER)) 
{/* Simply get the status again, which wastes time */ 
nStatus = i n p ( L S R_ PORT) ; 

} 

out p( THR_ PORT, * c h C h a r ) ; 

TheREADCOMM program also shows how to switch between the speed con- 
trolling ports, DLL andD LM .Thisisaccomplished by setting theDi vi sor _ latch _bi t 
bit in theLCR port register, as follows: 

nTempSt at us = i np( LCR PORT) ; 

out p( LCR PORT, nTempSt at us | DIVISOR LATCH BIT); 
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nSt at us = i n p ( DL M_ PORT) ; 

pri ntf ( " DL M_ PORT returned %2.2X\n", nStatus); 
nSt at us = i n p ( DL L_ PORT) ; 

pri ntf ( " D L L _ P 0 R T returned %2.2X\n", nStatus); 
out p( LCRPORT, nTempSt at us ) ; 

First, the program gets the current contents of the lcr port and saves the 
contents in mempst at us . Then the program writes to lcr port with nTempstat us 
logically 0 Rd with theDi vi sor latch bi T.Thisswitchesthemeaningof rbr port to 
dl l_ port and the meaning of thr port to dl m_ port . 

Besureyou reset lcr _ port after you havefinished setting (or checking) thebaud 
rate. You set the baud rateusing theidentifiersprefaced with baud in ether program. 

Summary 

I n thischapter, you learned about input and output using C , and how to use both file 
I/O and port I/O. 

• Files used for both program input and program output are vital to any 
program's operation. 

• Text-based files can be read, printed, edited, and otherwise used without 
conversion by people. Text files usually contain only printable, newline, and 
form-feed characters. 

• Binary files contain any bytes that a program must placein thefile. Generally, 
a binary file is intended for use by the program or by other programs and 
cannot be edited, printed, or read. 

• U sing temporary work files, a programmer can extend a program's data storage 
space to almost the amount of free space on the disk. W ork files can be text or 
binary, depending on the program's requirements. 

• Stream files are supported by many functions, can be text or binary, and are 
usually buffered and formatted. 
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• Every C program has five opened files: stdi n, stdout , stdaux, stdpr n, and 
stder r . Thesefiles are opened as stream files. 

• Low-level files are accessed with a minimum number of C functions and are 
usually unformatted and unbuffered. 

• C compilers provide console functions to access the screen and keyboard. 

• In PC compatible systems, your programs can access ports usi ng C. This access 
allows direct interaction with thedevice, without DOS or the BIOS. 
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Data Management: 
Sorts, Lists, and Indexes 

D ata management iswhat it'sall about. Almost all computer programsmanagedata— 
even asimplecomputergamemustmanageandaccessdatatoupdateitslistof current 
high scores. 

Sorting, merging, and purging. Indexed files. Tree access methods. Everyone 
knows what sorting is, but the other terms may be unfamiliar. M erging is the process 
of com bi n i n g two sorted f i I es an d creati n g a resu I tan t, sorted f i I e. P u rgi ng u ses a sorted 
fileto createa new filein which duplicate lines from the original file are eliminated. 
An indexed file (or in-memory data object) con si sts of two f i I es: themain datafileand 
a secon d , smaller indexfile. A tree access meth od offers fast search i n g an d sorted access 
to data. (T his chapter discusses B-trees.) 
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I'll use the creation of this book's index as an example of sorting, merging, and 
purging. For each chapter, I created a file in which each word is on a separate line (I 
simply changed all spacesto newline characters). I then sorted thefile, then purged it, 
which eliminates all duplicate words (and makes thefilesizemoremanageable). 

Then, I merged each chapter's file of unique words into one large file for the 
entire book. I then purged that file- even though each chapter's file contains only 
unique words, other chapters might contain some of these words too. After this final 
purge, I had a file of unique words in the book. After a quick session with an editor, 
I deleted any words that were not index material, leaving only the important words. 

I used programs that I created to sort, merge, and purge as part of this chapter. 
The DOS SO RT utility is limited to files under 64K, but the sort program in this 
chapter islimited onlybytheavailablememory.Themergeand purgeutilitiesarenot 
part of DOS. I hopethey provetobevaluableadditionsto your stableof programming 
tools. 



Sorting 

Sortingafilecan beboth easy and difficult. I t'seasybecauseC hasa sort function called 
qsorto that is part of the library. This function's performance is acceptable. The 
difficult part isreading in thefilesand other programmingoverhead. You must provide 
a com pare function that qs or t { ) can use. 

When you write a program in which you do not know the amount of data that 
theuser will input, you must rely on dynamic memory allocation. Thisisnotaproblem 
with theqsor t ( ) function: you pass a singlearray of pointers to thedata being sorted 
and, when q s o r t ( i returns, use the (now sorted) array of pointers to access the data in 
sorted order. When you usethistechniquewith character strings, it reduces overhead 
and increases the program's performance because only the pointers are moved in 
memory, not the strings. 

Listing 10.1, SORTFILE.C, sorts the input from stdi n and writes the sorted 
resultstos t do u t . If you usel/O redirection, theprogram could sort afileand placethe 
results into a new file. Unlike the DOS SORT command, SORTFILE always sorts 
from column one. (Adding thecapabilityto sort from any other column isan exercise 
I'll leave to you.) 



322 



Data Management: Sorts, Lists, and Indexes 



Listing 10.1. SORTFILE.C. 

/* SORTFILE, written 1 9 9 2 by Peter D. Hipson 

* This program sorts from stdin and sends the results 

* to stdout. If your PC has memory mo dels, you must 

* compi I e wi t h the LARGE model . 

*/ 



#i nc I ude <st di o. h> 

#i nc I u d e <s t r i n g . h > 

#i nc I ude <pr oces s . h> 

#i nc I ude <ma I I o c . h > 

finclude <search.h> 



Make includes first part of file 
For string functions 
For exi t ( ) , etc. 

For ma I I o c ( ) , c a I I o c ( ) , r e a I I o c ( ) , f r e e ( ) 
For qs o r t ( ) . . . 



int main(void); // Define main() and the fact that this program 
/ / does not use any passed p a r a me t e r s 



int compare! voi d *argl, void * a r g 2 ) ; 



tdefine MAX_ CHARACTE RS 3 2 7 6 7 /* Total max i mu m c h a r a c t e r s */ 

#def i ne MAX_LI NES 1 5 5 0 0 / * Tot a I maxi mum I i nes */ 

tdefine Bl GESTLI NE 512 /* Largest line readable from keyboard */ 

tdefine MAX_ BLOCKS 128 /* Allow 128 * MAX_ C HA RACT E RS of memory */ 

/* Although these variables are defined as external, they could 

* be defined inside the function or allocated dynamically, 

* depending on the program's needs and the available memory. 

*/ 

char szl nput[ Bl GEST LI NE] ; 

char *szBuffer; 

char * pBI oc ks [ MAX_ BLOCKS] ; 

char *pBuffer [ MAXLI NES] ; 

int nCur r ent Bl oc k =0; 

int nBufferPoi nter = {MAXCHARACTERS}; 

int n L i n e = 0 ; 

int ma i n ( ) 



continues 
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Listing 10.1. continued 



i nt i ; 

/* Use fpri ntf(stderr. . . ) to force prompts and error messages 

* to be displayed on the user's screen regardless of whether 

* the output has been redirected. 

*/ 

fpri ntf(stderr, 

"\ n" 

"Peter's SORTFILE: Sorts large files at the speed of light!\n" 

"\ n" 

syntax: \ n " 

sor t f i I e <i nput f i I e >out put f i I e \ n" 

"\ n" 

where: \n" 

the program's I/O is r e d i r e c t e d \ n \ n " ) ; 

fpri ntf(stderr, "Reading input...\n"); 

while ( g et s ( s z I n put ) ) 

{ 

if ( ( nBuffer Poi nter + s t r I e n ( s z I n pu t ) ) > MA X_ C H A RACT E R S ) 
{ // The line won't fit! Allocate new memory: 

szBuffer = (char * ) ma I I o c ( MAX_C HARACTE RS ) ; 

fprintf(stderr, " Allocating buffer ( 3 2 K ) . \ n " ) ; 
nBufferPoi nter = 0; 

pBI ocks[ nCur rent Bl ock] = szBuffer; 

+ + nCu r r e nt Bl ock; 

i f ( szBuffer == NULL) 

{ 

fpri ntf(stderr, "System sort memory exceeded, can't \ 
s o r t . \ n " ) ; 
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exi t ( 16) ; 

} 

} 

pBuffer[ nLi ne] = &szBuffer[ nBufferPoi nter]; 

strcpyt pBuffer[ nLi ne], s z I n put ) ; 

// The + 1 skips over the terminating NULL in each string. 
nBufferPoi nter += st rl en( szl nput) + 1; 

i f ( ++n L i ne >= MAX_ LI NES) 

{ // Too many lines! End the program. 

fprintf(stderr, "Too many lines - cannot sort.\n"); 

exi t ( 16) ; 

} 

} 

// 

/ / Now sor t the input lines 

// 

f p r i n t f ( s t d e r r , "Sorting, %d lines, in %d buffers. \ n", 
nLi n e , 

nCur rent Bl ock) ; 

qs o r t ( ( v o i d * ) pBuf f er , 
( si ze t) nLi ne, 
s i z eof ( c ha r * ) , 
compare) ; 

f p r i n t f ( s t d e r r , " Wr i t i n g output... \n"); 

for ( i =0; i < nLi ne; i ++) 

{ 

p r i n t f ( " %s \ n " , p B u f f e r [ i ] ) ; 

} 



f p r i n t f ( s t d e r r , " \ n " ) 
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Listing 10.1. continued 



for (i =0; i < nCurrentBlock; i ++) 

{ 

f r ee( pBI oc ks [ i ] ) ; 

} 

return ( 0) ; 

} 



i nt c o mp a r e ( 

char * * a r g 1 , 
char * * a r g 2 ) 



return st rcmp( *( char**) argl, *(char**)arg2); 

} 



Note the declaration of thecomparei ) function: 

i nt compare( char **argl, char * * a r g 2 ) ; 

Thefunctionhastwo parameters. I treceivesitsparametersaspointersto pointers 
to strings. Got that? You pass an array of pointers to strings, then qsort ( ) passes 
pointersto dementsin thearray to compare. I tcomparesthestringsthesetwo pointers 
address, and returnsavaluebased on this comparison. The compare function returns 
zero if thetwo parameters areequal, less than zero if thefirst parameter islessthan the 
second, and greater than zero if thefirst parameter is greater than the second. 

Next are some defined identifiers: 

tdefine MAX_ CHARACTE RS 3 2 7 6 7 /* Total ma x i mu m characters */ 

tdefine MAX_ LINES 1 6 3 8 3 /* Total maximum lines */ 

tdefine Bl GESTLI NE 512 /* Largest line readable from keyboard */ 

tdefine MAX_ BL OCKS 128 /* Allow 128 * MAX _ C H A RACT E RS of memory */ 

M emory is allocated in blocks of 32K using the max characters identifier. A 
maximum of 16K lines can be sorted (with a 4-byte pointer, about 16K pointers can 
fit in 64K). The largest lineallowed is 512 bytes, and up to 128 callscan bemadeto 
the memory allocation functions (which allocates more memory than you'll find on 
aPC). 



326 



Data Management: Sorts, Lists, and Indexes 



The external variables declared (they could be declared as internal static 
variables) define an input buffer, sz But fer i ] , a generic character pointer, an array of 
pointers to each block of memory (so that the blocks can be freed later), and an array 
of character pointers (* pBuf f er [ ] ) that point to each line that will be sorted: 

char szl nput[ Bl GEST LI NE] ; 

char *szBuffer; 

char * pBI oc ks [ MAX_ BLOCKS] ; 

char *pBuffer [ MAXLI NES] ; 

i n t nCur rent Bl ock =0; 

i nt nBufferPoi nter = { MAX_ CHARACTE RS } ; 

i n t n L i n e = 0 ; 

The program receives its input from thekeyboard and writes to the terminal. 
Therefore, if theprogram isused asapipeor with I/O redirection, you must be sure 
that error messages do not get redirected. In Chapter 9, "Disk Files and Other I/O," 
you learned that thestandard stream stderr does not get redirected, butst do ut does. 
T herefore, if the program's output is written to s t do u t and messages to the user are 
written to s t d e r r , you can be sure that messages to the user are not mixed with the 
program's output. 

Toaccessstder r ,you usethef pr i ntf ( st der r , . . . ) ; statement, asshown in the 
following code fragment: 

fpri nt f ( s t de r r , 
" \ n " 

"Peter's SORTFILE: Sorts large files at the speed of light!\n" 
" \ n " 

syntax: \ n " 

s o r t f i I e <i n p u t f i I e >outputfi I e \ n " 

"\ n" 

where: \ n " 

the program's I / 0 i s r e d i r e c t e d \ n \ n " ) ; 

fprintf(stderr, "Reading input... \ n " ) ; 

After providing the opening messages to the user, the program reads the input 
from s t d i n . TheC function gets ( ) does fine in thiscontext. After reading a line, the 
program checks whether there is enough room in the current buffer for the string. If 
there is not enough room, the program allocates a new buffer and displays a message 
that the buffer has been allocated: 
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wh i I e ( g et s ( s z I n put ) ) 

{ 

if ( ( nBuff erPoi nter + strlen(szlnput)) > MAX_ C H ARACT E RS ) 
{ // The line won't fit! Allocate new memory: 

szBuffer = (char * ) ma I I o c ( MAX_ CHARACTE RS ) ; 

f pr i ntf ( st der r , " Allocating buffer ( 3 2 K) . \ n") ; 
nBufferPoi nter = 0; 

pBI ocks[ nCurrentBI ock] = szBuffer; 

++n Cu r r ent Bl oc k ; 

i f (szBuffer == NULL) 

{ 

fprintf(stderr, "System sort memory exceeded- - cannot \ 
s o r t . \ n " ) ; 

exi t ( 16) ; 

} 

} 

Now that thereis enough room in thebuffer for thestring, theprogram sets the 
poi nter array (pBuf fer [ ] )tothestring'seventual location, then copiesthestring to the 
buffer. T he intermediate buffer is used to help prevent buffer overflow (otherwise the 
program would haveto stop filling a block of memory at least 512 bytesbeforetheend 
of th e bl ock) . T h ecal I to s t r c p y ( i does n ot taketoo much overh ead . T h e program al so 
updates the pointer into the block of memory, in preparation for the next string. 

pBuf f er [ n L i ne] = &szBuffer[ nBufferPoi nter] ; 

strcpy(pBuffer[nLine], szlnput); 
// The + 1 skips over the terminating NULL in each string. 
nBufferPoi nter += s t r I e n ( s z I n p u t ) + 1; 

A bit of error checking comes next, to be sure that the program does not read in 
too many lines: 

i f ( + + n L i ne >= MAX_LI NES) 

{ // Too many lines! End the program. 

fprintf(stderr, "Too many I i nes - - cannot sort.\n"); 

exi t ( 16) ; 

} 

} 

After theinputfilehad been read, theprogram callsqso r t ( ) tosortthefile, using 
the compare (described previously): 
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qsort((void *) pBuffer, 
( si ze_t) nLi ne, 
s i z eof ( c h a r * ) , 
compare) ; 

When q s o r t ( ) returns, the program uses pn ntf( ) to write the final sorted 
output: 

fpri ntf(stderr, " Wr i t i n g output... \n'); 

for ( i =0; i < nLi ne; i + + ) 

{ 

p r i n t f ( " %s \ n " , pBuffer[i ]); 

} 

Because the pr i ntto output goes to st do ut , the output could be redirected to a file. 
Finally, the blocks of memory are freed and the program ends: 

for (i = 0; i < nCurrentBI ock; i++) 

{ 

f r ee( pBI ocks [ i ] ) ; 

} 

The compare function, which is called byqsorto in the main program, is 
simple. T heprogram callss trcmpo .If you wanttheprogram to ignorecase, you could 
callstri cmp( i instead. You could also create your own function tocomparethestrings, 
but C's functions work well enough. 

i nt c o mpa r e ( 

char * * a r g 1 , 
char * * a r g 2 ) 

{ 

return strcmp(*argl, * a r g 2 ) ; 

} 

TheSORTFILE program can sort files up to 500K, depending on theDOS 
version). You could useSO RTF I LE also with I/O redirection or asa filter with DO S's 
pipe operator, | . 



Merging 

No matter how much memory you have available, eventually you will want to sort a 
filethat istoo large. You could sort thefilefrom thedisk. Another method isto break 
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thefileinto smaller parts that will fit in memory, sort these parts, then combinethe 
sorted parts into a final sorted file that contains the sum of the parts. The process of 
breaking a file into smaller, more manageable parts, called a sort/merge, is a common 
technique on mainframes and minicomputers. 

Tokeeptheprogramsin thischapter as simpleaspossible(but wait until you see 
theBTREE program later in thechapter), I created separate merge and sort programs. 
Listing 10.2, M ERG FILE. C, does not uses t d i n for its input because you must have 
two files to perform a merge. 

Listing 10.2. MERGFILE.C. 

/* MERGFILE, written 1 9 9 2 by Peter D. Hipson 

* This program merges two sorted files into one large 

* sorted file. If your PC has memory models, you must 

* compile with the LARGE mo del. 

*/ 

#include <stdlib.h> // For standard functions 
#include <stdio.h> // Make includes first part of file 
#i n c I u d e <string.h> // For string functions 
tinclude <process.h> // For exit(), etc. 

#i n c I u d e < ma I I o c . h > // For malloc(), calloc(), r e a I I o c ( ) , free() 
#i nc I ude <sea r c h . h > / / For gs o r t ( ) . . . 

int ma i n ( i n t argc, char * a r g v [ ] , char * e n v p [ ] ) ; 

int comparef char **argl, char * * a r g 2 ) ; 

#define Bl GESTLI NE 512 /* The largest readable line */ 
#define NEED_ RECORD 1 /* A record is needed from the file */ 
tdefine ENDOFFI LE 2 /* This file is finished */ 
tdefine AL L_ OK 3 /* No record needed; not EOF */ 

/* Although these variables are defined as external, 

* they could be defined inside the function or 

* allocated dynamically, depending on the program's 

* needs and available memory. 

*/ 
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char szl nputl[ Bl GEST LI NE]; 
char szl nput2[ Bl GEST LI NE] ; 

i n t ma i n ( 

i nt a r g c , 
char * a r g v [ ] , 
char * e n v p [ ] 
) 



FILE *l n F i I el; 

FILE * I n F i I e 2 ; 

FILE * 0 u t F i I e ; 

char s z Pr ogr a m[ 3 0 ] ; 

/* Strings for _splitpath() (which parses a filename) */ 

char szDr i ve[ _ MAX_ DRI VE] ; 

char szDi r[_MAX_DI R] ; 

char s z F n a me [ _ MAX_ F NAME ] ; 

char s z Ex t [ _ MAX_ EXT] ; 

i nt i ; 

i nt j ; 

i nt nCompar e = 0; 

i nt n F i I eOneStat us = NE E D_ RECORD; 

i nt n F i I eTwoStat us = NE E D_ RECORD; 



/* Use fpri ntf(stderr. . . ) to force prompts and error messages 

* to be displayed on the user's screen regardless of whether 

* the output has been redirected. 

*/ 

_s pi i t pa t h( a r g v[ 0] , 
s z D r i v e , 
s z Di r , 
s z F n a me , 
szExt ) ; 
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Listing 10.2. continued 



strncpyf szProgram, szFname, sizeof(szProgram) - 1); 

if ( a r gc <= 3 ) 

{ 

fpri n t f ( s t d e r r , 

" \ n " 

" %s ■ \ n " 
■ \ n " 

"Peter's MERGEFILE: Merges two sorted files into one! \ n " 
" \ n " 

syntax: \ n " 

%s i n p u t f i I el i n p u t f i I e 2 outputfi I e \ n " 

" \ n " , 

szProgram, 
szProgram) ; 

r et ur n( 16) ; 

} 

fprintf(stderr, "Reading input... \ n " ) ; 

I n F i I e 1 = f o p e n ( a r g v [ 1 ] , " r t " ) ; 
I n F i I e 2 = fopen( argv[ 2] , "rt"); 
Out F i I e = f o pen ( ar g v [ 3 ] , " wt " ) ; 

whi I e ( 

n F i I eOneStat us ! = ENDOFFI LE | 
n F i I eTwoStat us ! = ENDOFFI LE) 

{ 

s wi t c h ( n F i I e On eS t a t u s ) 

{ 

case N E E D_ RECORD: /* Read a record */ 

if (fgets(szl nputl, s i z eof ( s z I n pu 1 1 ) , InFilel) == NULL) 

{ 

n F i I eOneStatus = ENDOFFI LE; 

} 

else 

{ 

n F i I eOneStatus = A L L _ OK ; 
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break; 



case AL L _ OK: 
break; 



/ * Not hi ng needed */ 



case END OF FI LE 
break; 



/* Can't do anything */ 



swi t ch( nFi I eTwoStat us) 

{ 

case NEE D_ RECORD: /* Read a record */ 

if ( f gets( szl n p u 1 2 , s i z eof ( s z I n p u 1 2 ) , I nFi I e 2 ) == NULL) 

{ 

nFi I eTwoStat us = ENDOFFI LE; 

} 

el se 

{ 

nFi I eTwoStatus = AL L _ 0 K ; 

} 

break; 

case A L L _ 0 K : /* Nothing needed */ 

break; 

case ENDOFFI LE: /* Can't do anything */ 
break; 



if ( nFi I eOneStatus == ENDOFFI LE) 



if ( nFi I eTwoStat us I = ENDOFFI LE) 



f put s( szl n p u 1 2 , Out Fi I e) ; 

nFi I eTwoStat us = NE E D_ RECORD; 



else 



if ( nFi I eTwoStat us == ENDOFFI LE) 



continues 
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Listing 10.2. continued 

if ( n F i I eOneSt at us ! = ENDOFFI LE) 

{ 

f put s ( sz I n put 1 , Out F i I e ) ; 

n F i I eOneSt at us = NEED_RECORD; 

} 

} 

else 

{ 

n Compare = s t r c mp ( s z I n p u 1 1 , sz Input 2); 

if (nCompare < 0) 

{/ * File one is written * / 

f put s ( sz I n put 1 , Out F i I e ) ; 

n F i I eOneSt at us = NEED_RECORD; 

} 

else 

{ 

if (nCompare > 0) 

{/ * File t wo is wr i 1 1 en */ 

f p ut s ( s z I n p u 1 2 , Out F i I e ) ; 

n F i I eTwoStat us = NE E D_ RECORD; 

} 

else 

{/* They are the same; write both */ 
f put s ( s z I n pu 1 1 , Out F i I e ) ; 
f p ut s ( s z I n p u 1 2 , Out F i I e ) ; 
n F i I eOneSt at us = NEEDRECORD; 
n F i I eTwoStat us = NE E D_ RECORD; 

} 

} 

} 

} 

} 

f cl ose( I n F i I el) ; 
f cl ose( I n F i I e2) ; 
f cl ose( Out Fi I e) ; 

return ( 0) ; 

} 
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M erging files is a simple process. Because this program does not use advanced 
techniques, I will dispensewith theline-by-lineanalysisof theprogram'scodeand refer 
instead to the program's flowchart, shown in Figure 10.1. 





FigurelO.l. The flowchart for M ERGFILE.C. 



First, theprogram opensthetwo input files and theoutput file. If errorsdo not 
occur in this stage, theprogram reads a record from both input files. After the records 
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are read, the program does itscomparisons (taking into consideration possibleend-of- 
file conditions), and writes the correct record. When the program reaches the end of 
both input files, itclosesall thefilesand ends. Itisasimpleprogram thatworksquickly. 

When writing a merge function, you must consider that one file may be (and 
usually is) shorter than theother.Themergeprogram must besurethatthelonger file's 
records are written to the output. 

Purging 

O ne often needed (and hard to find) program is a purge program, which is used to 
delete duplicates (sometimes called de-dup) from a file. You might want to delete 
duplicates, for example, from a mailing list or a word list. 

ThePURGFILE.C program in Listing 10.3 performstwo functions. Part of the 
program works like M ERG FILE (Listing 10.2). Unlike M ERGEFILE, however, 
PU RG F I L E does not write duplicates to the output file. 

Listing 10.3. PURGFILE.C. 

/* PURGFILE, written 1 9 9 2 by Peter D. Hipson 

* This program me r g e s and purges in one step. If your 

* PC has memory models, you must compile with the 

* LARGE model . 

*/ 

#include <stdlib.h> // For standard functions 
#include <stdio.h> // Make includes first part of file 
#i n c I u d e <string.h> // For string functions 
#include <process.h> // For exit(), etc 

#i n c I u d e < ma I I o c . h > // For ma I I o c ( ) , calloc(), real I o c ( ) , free() 
#i nc I ude <sea r c h . h > / / For gs o r t ( ) . . . 

int main(int argc, char * a r g v [ ] , char * e n v p [ ] ) ; 

int comparef char **argl, char * * a r g 2 ) ; 

tdefine Bl GESTLI NE 512 /* The largest readable line */ 
#define NEED_ RECORD 1 /* A record is needed from the file */ 
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#def i ne E N D_ OF _ F I LE 2 
#d e f i n e ALL OK 3 



/ * This file is finished */ 

/ * No record needed, not EOF */ 



/* Although these variables are defined as external, they could 

* be defined inside the function or allocated dynamically, 

* depending on the program's needs and available memory. 

*/ 



char szl nput[ Bl GEST LI NE] ; 
char szl nput 1[ Bl GESTLI NE] ; 
char szl nput2[ Bl GEST LI NE] ; 



i n t ma i n ( 

i n t a r g c , 
char * a r g v [ ] , 
char *envp[ ] 
) 



{ 



FILE *l n F i I el; 
FILE * I n F i I e 2 ; 
FILE * Ou t Fi I e; 



char szPr ogram] 30] ; 



/* Strings for _ s p I i t pa t h ( ) , which parses a file name */ 
char szDr i ve[ _ MAX_ DRI VE] ; 
char szDi r[_MAX_DI R] ; 
char s z F n a me [ _ MAX_ F NAME ] ; 
char s z Ex t [ _ MAX_ EXT] ; 



i nt i ; 

i nt j ; 

i nt nCompar e = 0; 

i nt n F i I eOneStat us = NE E D_ RECORD; 

i nt n F i I eTwoStat us = NE E D_ RECORD; 



/* Use fpri ntf{ stderr. . . ) to force prompts and error messages to be 
* displayed on the user's screen regardless of whether the output 

continues 
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Listing 10.3. continued 

* has been redirected. 

*/ 

spl i tpath(argv[ 0], 
s z Dr i v e , 
s z Di r , 
s z F n a me , 
szExt ) ; 



strncpyf szProgram, szFname, sizeof(szProgram) - 1); 

if ( a r gc <= 3 ) 

{ 

fpri ntf(stderr, 

" \ n " 

" %s ■ \ n " 
" \ n " 

"Peter's PURGEFILE: Merges two sorted files, \n" 
purging all duplicate I i n e s ! \ n " 

" \ n " 

inputfilel and i n p u t f i I e 2 can be the same file,\n" 
if you want to de-dup only one file.\n" 

" \ n " 

syntax: \ n " 

"\ n" 

%s inputfilel i n p u t f i I e 2 o u t p u t f i I e \ n " 

" \ n " , 

szProgram, 
szProgram) ; 

r et ur n( 16) ; 



I n F i I e 1 = f o p e n ( a r g v [ 1 ] , " r t " ) ; 
I n F i I e 2 = fopen(argv[2], "rt"); 
Out F i I e = f o pen ( ar g v [ 3 ] , " wt " ) ; 

whi I e ( 

n F i I eOneStat us ! = ENDOFFI LE | 
n F i I eTwoStat us ! = ENDOFFI LE) 
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wh i I e ( 

nFi I eOneStatus == N E E D_ RECORD 
nFi I eTwoSt at us == N E E D_ RECORD) 



{ 



swi tch(nFi I eOneStatus) 

{ 

case N E E D_ RECORD: /* Read a record */ 

if ( f get s( sz I nput , s i z e of ( s z I n p u t ) , I nFi lei) == NULL) 

{ 

nFi I eOneStat us = END OF FI LE; 

} 

else 

{ 

if ( st r c mp( s z I n put , sz I n put 1 ) ! = 0) 

{ 

st r c py ( s z I n put 1 , s z I n pu t ) ; 
nFi I eOneStatus = A L L _ OK ; 

} 

} 



break; 



case A L L _ 0 K : /* Nothing needed */ 

break; 

case ENDOFFI LE: /* Can't do anything */ 
break; 

} 

s wi t c h ( n F i I eTwo S t a t u s ) 

{ 

case NEED_ RECORD: /* Read a record */ 

if ( f get s( sz I nput , s i z e of ( s z I n p u t ) , I nFi I e 2 ) == NULL) 

{ 

nFi I eTwo St a t us = ENDOFFI LE; 

} 

else 

{ 

if ( strcmp( szl nput, sz I n put 2 ) 1=0) 

{ 

continues 
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Listing 10.3. continued 

strcpy(szlnput2, szlnput); 
n F i I eTwoSt at us = AL L_ OK ; 

} 

} 

break; 

case A L L _ 0 K : /* Nothing needed */ 

break; 

case ENDOFFI LE: /* Can't do anything */ 
break; 

} 

} 

if ( n F i I eOneSt at us == ENDOFFI LE) 

{ 

if ( n F i I eTwo St at us ! = ENDOFFI LE) 

{ 

f put s( sz I nput 2, Out Fi I e) ; 

n F i I eTwo St at us = N E E D_ RECORD; 

} 

} 

else 

{ 

if ( n F i I eTwoSt at us == ENDOFFI LE) 

{ 

if ( n F i I eOneStatus ! = ENDOFFI LE) 

{ 

f put s ( sz I n put 1 , Out F i I e ) ; 

n F i I eOneSt at us = NEED_RECORD; 

} 

} 

else 
{ 

n Compare = s t r c mp ( s z I n p u 1 1 , szlnput 2); 

if (nCompare < 0) 

{/ * File one is wr i 1 1 en */ 

f put s ( sz I n put 1 , Out F i I e ) ; 

n F i 1 eOneSt at us = NE ED_ RECORD; 
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C C C 
III] 

c cc 



} 

el se 

{ 

if (nCompare > 0) 

{/ * File t wo is wr i 1 1 en */ 

f put s( sz I nput 2, Out Fi I e) ; 

n F i I eTwoStat us = N E E D_ RECORD; 

} 

else 

{/* They are the same; write one and discard the 
other. */ 

f put s( sz I nput 1, Out Fi I e) ; 

n F i I eOneStat us = N E E D_ RECORD; 

n F i I eTwoStat us = N E E D_ RECORD; 

} 

} 

} 

} 

} 

f c I os e( I n Fi I el ) ; 
f cl ose( I n F i I e2) ; 
f cl ose( OutFi I e) ; 

return ( 0) ; 

} 



Purging duplicate records from a single file is not difficult. First the program 
reads a line. Then theprogram discards the line if it isthesameasthepreviousline, 
or saves the line if it is different from the previous line. PU RGFILE performs a merge 
and a purge at the same time, however, making theprogram a bit more complex. 

To usePU RGFILE to purgeasinglefile, you simply specify thesamenametwice 
or specify nul : asthesecond filename. (A second f ilen am em ust be specified to provide 
the output filename.) 

T heflowchart in F igure 10.2 shows how the PU RG F I L E program works. T he 
program does not use advanced techniques, so this section looks only at theflowchart, 
rather than each line of code. 
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C C C 
CC C 

c cc 



Asyou can seein Figurel0.2,theprogram beginsby opening thetwo inputfiles 
and the output file. If there areno errors in thefile-open stage, the program readsa 
record from each file (assuming that the program should read a record and that the 
program has not reached theend of thefile). 

After the records are read, the program makes its comparisons (taking into 
consideration possible end-of-file conditions), then writes the correct record. When 
the program has the same record from both files, it discards the second file's record, 
sets the flag indicating that it needs a new record from the second file, and saves the 
first file's record. 

When theprogram reaches theend of both inputfiles, it closes all thefilesand 
ends. 1 1 is a simple program that works quickly. 

W hen you write a purge function, remember that a record might be repeated 
many times. When your program finds a duplicate and therefore reads a new record, 
it still must test to be sure that it has read a unique record. The program might be 
reading a third duplicate, for example, that must also be discarded. 



Sorting, Merging, and P urging All in One 

Usually, a singleutility offers sort, merge, and purgefunctions. T histypeof utility will 
haveoneortwoinputfilenames, sortthefiles, purgetheduplicates, and provideasingle 
output file. 

A variation of a sort program isasort that works on afileof any size. The process 
to create th e u I ti m ate sort f ol I ows: 

1. Read thefile, stopping at theend of the file or when there is no more free 
memory. 

2. Sort this part of thefile. W rite the result of the sort to a temporary work file. 

3. If theprogram has reached theend of the file and there are no more records to 
read in, theprogram renames step 2'swork fileto the output file's name and 
ends the program. 

4. Again read thefile, stopping when there is no more free memory or when the 
end of thefile is reached. 
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5. Sort this part of the file. W rite the result of the sort to a second temporary 
work file. 

6. M erge the file created in step 2 with the file from step 5. Delete both of the 
files created by steps 2 and 5, and rename this new file using the namefrom 
step 2. 

7. Go to step 3. 

Linked Lists 

A linked list is a group of data objects in which each object has a pointer to the next 
object in the group. Everything that you do with linked lists can be performed in 
memory or as part of a disk file. 

Sometimes, sorting the data externally to the program (using the D 0 S SO RT 
program) is not enough. W hen a user isentering data, it is never acceptableto stop the 
program, exit theprogram, run asort, createasorted file, then start theprogram again. 

W e have become accustomed to having the computer do the work for us, and 
rightly so. A program should not require the user to do anything that theprogram can 
perform without the user's intervention. 

There are alternatives when data must be sorted. For example, when the user 
enters an item, theprogram can pause and usetheqsor t ( ) function to insert thenew 
item into thecurrent database. I f thedatabaseis large, however, thepausecould be so 
long that you could go get lunch! Even a simple insert at the beginning of a list can be 
timeconsuming— every record in thedatabasemustbemoved.Thesizeand number 
of these records can be the critical factor. 

M any programs must present the user's data in a sorted format. Because speed 
is critical, sorting each time the data is displayed usually is unacceptable— the data 
must be stored in sorted order. 

M any programs work to keep as much of the user's current data as possible in 
memory. Searching a largequantity of data in memory should benot only quick, but 
i n stan tan eou s! I f thedata is not well organ i zed , th e search m ust be I i n ear ( record after 
record). 0 n average, the program must look at half the records to find a matching 
record, assuming that the records are stored randomly. 
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In general, a linear search of a block of data or sorting after a data item has been 
added or edited is too slow and therefore inadequate. 

The program's data must be organized better than the order in which it was 
entered. One way to organize is to use a linked list. In a linked list, you start with a 
pointer that pointsto, or identifies, thefirst member of thelist. Each member (except 
the last) has a pointer that points to the next member in the list. T he last member's 
pointer isa null pointer to indicatetheend of thelist. Often thereisaseparatepointer 
to the last member in thelist— this enables you to add to the end of thelist. A single 
linked list is shown in Figure 10.3. 



Q 



Q 



Optional point er to 



Q 



Pointer to Die 
second member 



inter to He 
Hun.] rnertil.iei 



Pointer to the 
last member 



Figure 10.3. A si ngie linked list. 



W hen you add a new member to a linked list, theprogram simply followsthelist 
until it finds the member that will precede the new member and inserts the new 
member at that point. W hen the program must display sorted data to the user, it uses 
thelinked list pointersto find then ecessary data. B ecause th e I i n ks are al ready sorted , 
the program's performance is fast. 



Using Dynamic Memory 

Often you must rely on dynamic memory allocation (memory allocated using oneof 
thememory allocation functions) becauseyou cannot tell how much user data will be 
provi ded by the user. W hen al locati ng memory, the program m ust track each bl ock of 
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memory, usually with a linked list. In this situation, it may (or may not) be that the 
links are simply arranged in the order that the memory blocks are allocated. When a 
memory block is freed, it is removed from the linked list. 

The example program in this section allocates memory blocks for each record 
that the user enters. These blocks are pointed to by links. 



Disk-Based Lists 

When you createa linked list as a disk-based file, the list's members must be thesame 
size. I f your program hasdifferent si zed membersofasinglelinked list, thebest solution 
istouseasingleuni on to createa single record of the correct size. The size of theuni on 
is determined by its largest member, so the members will be the same size. 



Double Linked Lists 

In adoublelinked list, each member has a pointer not only to its successor in thelist, 
butalsotoitspredecessor. Figurel0.4showshowadoublelinkedlistiscreated. Notice 
thatthepointer totheend of thelist is mandatory. Thispointer isnecessary so that the 
end of thelist can be accessed. 
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lirst member 
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last rt 



i Pointer back to 

he fir-.t member 



) Pointer bach to 
ttie second member 



I Pointer back to 
fe third member 



I Pointer back to 
ttie n 1h member 





last member 






( 



Pointer to the 
last member 



Figure 10.4. A double linked list. 
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Figure 10.5 shows the structure's list pointers. (Figure 10.5 and Figure 10.4 are 
thebasisfor Figures 10.6 through 10.9.) 



Figure 10.5. TheCUSTO M ER structure's linked list pointers. 

You can perform a trick with a double linked list. When you add a member to 
a double linked list, the program can examine the key fields of the first and last 
members to determine whether the list should be traveled from the beginning or the 
end. T his increases the program's performance. (It doesn't make sense to start at the 
first member if the new member will be added near the end of the list.) 

Listing 10.4, theLI N K LI ST .C program, demonstratestheuseof adoublelinked 
list with dynamically allocated members. The program is simple, without much 
optimization. The program always has sorted access to the items in the list. 

Listing 10.4. LINKLIST.C. 

/* LI N K L I ST, written 1 9 9 2 by Peter D. Hipson 

* A double linked list program. This program has 

* better error checking than the CDB program. 

* To improve the program, make the ZIP code field a 

* character field. A character field is better for ZIP 

* codes because many non-US ZIP codes also 

* contain letters. 
*/ 




Always points to the last member of 
the list, unless the list has no members 



(Or NULLrtttiere is 
no next member) 



continues 
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Listing 10.4. continued 



#i nc I u d e <st r i ng. h> 

#i nc I u d e <ct ype. h> 

#i nc I u d e < s t d i o . h > 

#i nc I u d e <process. h> 

#i n c I u d e <s t d I i b . h > 

#def i ne TRUE 1 

#def i ne FALSE ( ! TRUE) 

tdefine I NCREMENTAMOUNT 1 /* Add one record at a time */ 

#def i ne CUSTOMER RECORD 1 
#def i ne SUPPLI ER_ RECORD 2 

/* Define the structure for the customer database. */ 

struct _ CUSTNAME ; 

typedef struct CUSTNAME { 



i nt 


nRecor dType; 


/ / 1 == Cus t o mer record. 


struct 


_ CUSTNAME * Next Cust o mer ; // Link to next, or NULL if none 


struct 


_ CUSTNAME * P r e v Cu s t o me r ; // Link to previous, or NULL if none 


char 


s z N a me [ 61] ; 


// 60 chars for name; 1 for null at end 


char 


szAddr 1[ 61] ; 


// 60 chars for address; 1 for null at end 


char 


s z Ad d r 2 [ 61] ; 


// 60 chars for address; 1 for null at end 


char 


szCi t y [ 2 6] ; 


// 25 chars for city; 1 for null at end 


char 


szSt at e[ 3] ; 


// 2-character state abbrev. plus null 


i nt 


1 Zi p; 


/ / Print as %5 . 51 d for leading 0 


i nt 


nRecordNumber; 


/ / Wh i c h record number? 


doubl e 


dSal esTotal ; 


// Amount the customer has purchased 


} CUSTNAME; 





typedef CUSTNAME near * NPCUSTNAME; 

typedef CUSTNAME * P CUST NAME ; 

void Gi veHel p( voi d) ; 

void ma i n ( ) 
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FILE * Da t a F i I e ; 

P C US T NAME Fi rstCustomer = NULL; 

P C US T NAME LastCustomer = NULL; 

P C US T NAME Customer = NULL; 

PCUSTNAME TempCus t o me r = NULL; 

char szFi I eName[ 257] ; 

char szBuf f er [ 2 5 7] ; 

nt n No t Done = TRUE; 

nt nRecord = 0; 

nt nDebug = FALSE; 

nt nNeedSavi ng = FALSE; 

double dSal es = 0.0; /* Forces loading of floating-point support */ 

printf(" Please enter customer save file name: "); 

gets(szFileName); 

DataFile = f o pen ( s z F i I e Na me , "wt"); 
if ( DataFi I e == NULL) 

{/* Test for file open. If the file can't be opened, exit with 
me s s a g e . * / 

p r i n t f ( " E RROR: File ' %s ' couldn't be opened. \ n", szFileName); 
exi t ( 4) ; 



fcl ose( DataFi I e) ; 

p r i n t f ( " De mo of a linked list concepts\n" 

" \ n " 

C o mma n d s are: \ n " 

A - Add a c u s t o me r / s u pp I i e r record.\n" 

D - Display current list.\n" 

X - Exit from program. \ n" 
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Listing 10.4. continued 



z 


Toggle debug mode.\n" 


? 


Display the co mma n d list." 


II M 

n 


Display the co mma n d list." 


s 


Save the list.\n" 


■ \ n " 
) ; 




n Re c o r d = 0; 




whi 1 e ( n Not Done) 




{ 




p r i n t f ( "Enter 


command ( A, D + , D- , S) ?") ; 



get s ( s z Buf f e r ) ; 

s wi t c h( sz But f er [ 0] ) 

{ 

case ' H' : /* Give some help */ 
case ' h ' : 
case ' ?' : 

G i v e He I p ( ) ; 

break; 

case ' A' : / * Add a record * / 
case ' a' : 

Customer = ( PCUSTNAME) cal I oc( si zeof ( CUSTNAME) , 
I NCREMENT_AMOUNT) ; 

pri ntf("Enter name %d: ", + + n Record); 
gets(szBuffer) ; 

szBuffer [ si zeof ( Customer - >szName) - 1] = '\0'; 
strcpyt Customer - >szName, szBuffer); 

if ( s t r I e n ( C u s t o me r - >s z Na me ) > 0) 

{/* Insert this record in the list, sorted by name. */ 
nNeedSavi ng = TRUE; 
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i f ( Fi rstCustomer == NULL) 
{ 

p r i n t f ( " I t is first record \ n " ) ; 
Customer - >NextCustomer = NULL; 
Customer - >PrevCustomer = NULL; 

Fi rstCustomer = C u s t o me r ; 
Last Cust omer = C u s t o me r ; 
Temp Customer = NULL; 



{ 

TempCustomer = Fi rstCustomer; 



whi I e ( TempCust omer ) 

{ 

if ( nDebug) 

{ 

pr i ntf ( "TESTI NG FOR ADD: ' %s ' ' %s ' \ n", 



if ( st r c mp( Cust omer - >sz Name, 
Te mp Cus t o me r - >s z Na me ) < 0 | 
TempCustomer == La s t Cus t o me r ) 



if ( strcmp( Customer - >szName, 

Temp Cu s t o me r - >s z Na me ) < 0 && 
TempCustomer == F i r s t Cu s t o me r ) 

{ 

if (nDebug) 

{ 

pri ntf( "Assi gni ng as f i r s t \ n " ) ; 

} 

Customer- >Next Custo me r = Fi rstCustomer; 
F i r s t C u s t o me r = C u s t o me r ; 
Customer- >Pr evCusto me r = NULL; 



else 



Cus t o me r - >s z 
TempCustomer 



Na me, 

- >s z Na me ) ; 



continues 
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Listing 10.4. continued 

Temp Customer = Customer- >Next Cust o me r; 
TempCustomer- >PrevCusto mer = Customer; 

} 

else 

{ 

if ( s t r c mp( Cu s t o me r - >s z Na me , 

Te mpCus t o me r - >s z Na me ) > 0 && 
TempCustomer == La s t Cus t o mer ) 

{ 

if ( n Debug) 

{ 

pri ntf( "Assi gni ng as I a s t \ n " ) ; 

} 

Cust omer - >PrevCustomer = 

L a s t C u s t o me r ; 

L a s t C u s t o me r = C u s t o me r ; 

Customer- >Next Cust o mer = NULL; 

Te mp Cus t o me r = Cus t o mer - 

>PrevCustomer; 

TempCust omer- > N e x t Cust omer = 
C u s t o me r ; 

} 

else 

{ 

if ( n Debug) 

{ 

pri n t f ( " Assigning inside \ 
I i s t \ n " ) ; 

} 

Customer - >PrevCustomer = 

TempCustomer - >PrevCustomer; 

Customer - >NextCustomer = 
TempCust omer ; 

Te mpCus t o me r - >P r ev Cu s t o me r = 
C u s t o me r ; 

TempCust omer = Cust omer - 
>PrevCustomer; 

Te mpCus t o me r - > N e x t Cu s t o me r = 
C u s t o me r ; 
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} 

} 



} 

el 
{ 

} 

} 

Customer - >nRecordNumber = nRecord; 

if ( ! nDebug) 

{ 

do 
{ 

printf(" Enter 1 for customer, 2 for supplier \ 
"); 

gets(szBuffer); 

ss c a nf ( s z Buf f er , "%d", (^Customer 
- > n Re c o r dType) ; 

} 

while ( Customer - >nRecordType != CUSTOMERRECORD 
&& 

Cust omer - >n Reco r dTy pe != S UP P L I E R_ RECORD) ; 



TempCustomer = NULL; 

s e 

TempCustomer = TempCustomer- >NextCust o me r; 



p r i n t f ( " E n t e r address line 1 : " ) ; 
gets(szBuffer) ; 

s z Buf f e r [ s i z eof ( Cus t ome r - >s z Ad dr 1 ) - 1] = '\0' 
strcpyf Customer - >szAddr 1, szBuffer); 

printf(" Enter address line 2: "); 
gets(szBuffer) ; 

s z B uf f e r [ s i z eof ( Cu s t o me r - >s z Ad d r 2 ) - 1] = '\0' 
strcpy(Customer - >szAddr2, szBuffer); 

pri ntf( "Enter City: " ) ; 
gets(szBuffer) ; 

szBuffer [ si zeof ( Customer - >szCi ty) - 1] = '\0'; 
strcpy(Customer->szCity, szBuffer); 
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Listing 10.4. continued 



pri ntf( "Enter state postal abbreviation: "); 
get s ( s z Buf f e r ) ; 

szBuffer[ si zeof ( Customer - >szState) - 1] = '\0'; 
strcpy(Customer - >sz St at e, s z Buf f er ) ; 

pri ntf( "Enter ZIP code: " ) ; 
get s ( s z Buf f e r ) ; 

s s ca nf ( s z Buf f er , "%ld", StCust omer - >l Zi p) ; 



pri ntf( "Enter total sales: " ) ; 
get s ( s z Buf f e r ) ; 

s scant ( szBuf f er , "%f", &C u s t o me r - >d Sa I es Tot a I ) ; 

} 

} 

else 

{ 

pri ntf("\aSorry, name must not be b I a n k ! \ n " ) ; 

} 

break; 



case ' V : / ; 

case ' z' : 
nDebug 
break; 



Debug mode toggle */ 
I nDebug; 



case ' D' : / : 
case ' d' : 



Display all records */ 



T e mp C u s t o me r = F i r s t C u s t o me r ; 
pri ntf( "Di spl ay c u s t o me r s \ n " ) ; 



whi I e ( TempCust omer ) 

{ 

if (nDebug) 

{ 

pr i ntf ( 

"Name ' %1 0 s ' Me %l p Next %l p Prev % I p \ n " , 
Te mpCu s t ome r - >s z Na me, 
TempCus t ome r , 
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TempCustomer - >Next Customer , 
T e mp C u s t o me r - >PrevCustomer) ; 

} 

else 

{ 

pr i ntf ( 

"Name ' %1 0 s ' Ci ty ' %1 0 s ' State ' %2s' " 

"ZIP ' %5 . 5 1 d ' \ n " , 

Te mp Cus t o me r ■ >s z Na me , 

Te mp C u s t o me r - >s z Ci t y , 

TempCustomer - >szState, 

Te mp C u s t o me r - >l Zi p) ; 

} 

TempCustomer = TempCustomer- >Next Cust o me r; 

} 

break; 

case 'X': /* Exit; prompt for save if needed */ 
case ' x' : 

n No t Done = FALSE; 

szBuffer[0] = '\0'; 

while ( nNeedSavi ng && 
szBuffer[0] == '\0' ) 

{ 

pri ntf( "\nSave the data? ( y | n ) " ) ; 

get s ( s z Buf f e r ) ; 

i f ( szBuff er [ 0] == ' n' 
szBuff er[ 0] == ' N' ) 

{ 

nNeedSavi ng = FALSE; 

} 

else 

{ 

if ( szBuff er [ 0] I = ' y' && 
szBuf f er [ 0] ! = ' Y' ) 

{ 
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Listing 10.4. continued 

pri ntf( "\nWrong answer, " 

"please respond wi t h ' y ' or ' n ' " ) ; 

szBuff e r [ 0 ] = ' \0' ; 

} 

} 

} 

if ( ! nNeedSavi ng) 

{/* Do not need to save, so just exit */ 
break; 

} 

/* Else fall through to save routines */ 

case ' S' : /* Save all records */ 
case ' s' : 

pri ntf( "Savi ng c u s t o me r s \ n " ) ; 

Data File = f open( sz Fi I eName, "wt"); 

if ( DataFi I e == NULL) 

{/* Test for file re-open; if file can't be opened, exit 
wi t h message */ 

pr i n t f (" ERROR: File ' %s ' couldn't be opened. \n", 
s z F i I e Na me ) ; 

exi t ( 4) ; 

} 

TempCustomer = F i r s t Cu s t o me r ; 

whi I e ( TempCust omer ) 

{ 

if ( nDebug) 

{ 

f pr i nt f ( Dat a Fi I e, 

"Name ' %1 0 s ' Me %l p Next %l p Prev %lp\n", 
Te mpCu s t ome r - >s z Na me, 
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Te mpCus t o me r , 

TempCustomer - >NextCustomer, 
TempCustomer->PrevCustomer); 



else 



f pr i nt f ( Dat a F i I e, 

"Name ' %1 0 s ' City %1 0 s ' State ' %2s' " 

"Zl P ' %5. 51 d' \n", 

Te mp C u s t o me r - >s z Na me , 

Te mp C u s t o me r - >s z Ci t y , 

Te mp C u s t o me r - >s z St a t e, 

Te mp C u s t o me r - >l Zi p) ; 



TempCustomer = TempCustomer- >Next Cust o me r; 

} 

nNeedSavi ng = FALSE; 
f c I o s e( Dat a F i I e ) ; 



" \ n " 

"This program shows how a double linked list is created a n d \ n " 
"used. It enables you to add records, display the list of\n" 
"records (which are always sorted by name), and save the\n" 
"list of records to the disk f i I e . \ n " 
" \ n " 

"LI N K L I ST supports the following c o mma n d s : \ n " ) ; 



break; 



void 



Gi veHel p( ) 



p r i nt f ( 



p r i nt f ( 

" \ n " 



continues 
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Listing 10.4. continued 



Add a customer/supplier record. \n" 
Adds a record. Each added record is pi a c e d \ n " 
in the list in the correct order. Added\n" 
records are sorted by n a me . \ n " ) ; 



p r i n t f ( 
"\n" 



Display current I i s t . \ n " 

Prints the current list of records in sorted\n" 
order. This list contains name and address\n" 
information or, in the debug mode, name a n d \ n " 
pointer i n f o r ma t i o n . \ n " ) ; 



p r i n t f ( 
"\n" 



Exit from program. \ n" 

Ends the program. If records have been a d d e d \ n " 
and not saved, prompts for save. All saves\n" 
are made to the file specified when the\n" 
program was started. \n"); 



p r i n t f ( 

" \ n " 



Toggle debug mo d e . \ n " 

Changes the information displayed for the\n" 
user. When on, debug mode shows where the n e w I y \ n " 
entered name is being placed in the list, and \ 
t he\ n" 

list pointers are displayed when a display command \ 
i s \ n " 

entered. \ n") ; 



p r i n t f ( 
"\n" 



Display the co mma n d I i s t . \ n " 
Display the co mma n d I i s t . \ n " 
Displays this help i n f o r ma t i o n . \ n ' 



p r i n t f ( 
"\n" 
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C C C 
III] 

c cc 



S - Save the I i s t . \ n " 

Saves (to the specified save file) the current \ 
I i s t \ n " 

of records in sorted order. This list contains \ 
n a me \ n " 

and address information or, in the debug mode,\n" 
n a me and pointer i nformati on. \ n" 

■ \ n " ) ; 



p r i nt f ( 

"Additional feature: This program includes a\n" 
"prompt to save when the exit command is given. \n" 
"This prompt is given only if the records have\n" 
"not been saved since the last added record. \ n " ) ; 

pr i ntf ( 

"Additional feature: This program has a debug mode so that\n" 
"the user can see how the program works. The debug mode \ 
e n a b I e s \ n " 

"the user to print the linked list and its pointers. \ n " ) ; 

} 



Thisprogram wasdeveloped from theC D B.C program, which waspresented in 
Chapter 8, "Dynamic Memory Allocation." In this section, you look at the 
program, and the code that manages the linked list. First, in the following code 
fragment, is a nonspecific structure definition (yes, this is a definition, not a 
declaration) that creates the _c us t name structure name: 

struct CUSTNAME; 

T his allows _custname to be used in the declaration of the structure as a set of 
pointers, as the third and fourth linesin thefollowing code show: 

typedef struct _CUSTNAME { 

i nt nRecordType; // 1 == Customer record, 
struct _CUSTNAME * Nex t Cu s t o me r ; // Link to next, or NULL if none 
struct _CUSTNAME * P r e v Cu s t o me r ; // Link to previous, or NULL if none 
char s z Na me [ 6 1 ] ; // 60 chars for name; 1 for null at end 
char szAddr 1[ 61] ; // 60 chars for address; 1 for null at end 
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char szAddr 2[ 61] ; 

char s z Ci t y [ 2 6] ; 

char szState[ 3] ; 

i nt I Zi p; 



60 chars for address; 1 for null at end 

25 chars for city; 1 for null at end 

2 - c ha r ac t er state a b b r e v . plus null 

Print as %5 . 5 1 d for leading 0 

Wh i c h record number? 

Amount the customer has purchased 



i nt n Rec o r d N u mbe r ; 
doubl e dSal esTotal ; 



} CUSTNAME; 

Thissection of thee u s t n a me structuredeclaresmembersthatpointtothenextmember 
or the preceding member in the linked list. 

Thefollowingcodeshows how the pointers to thefirst and last members in the 
linked list are defined: 

PCUSTNAME Fi r st Cust omer = NULL; 
PCUSTNAME LastCustomer = NULL; 

These lines could have been coded as 

struct _ CUSTNAME *Fi rstCustomer; 
struct _ CUSTNAME * L a s t Cu s t o me r ; 

I suggest that you usethepointernamesdefined (if you writeyourstructureprototype 
as I do) when you create thetypedef structure. 

N ext, afew pointersarecreated for theprogram to usewhen a member iscreated 
or inserted into the list: 

PCUSTNAME Customer = NULL; 
PCUSTNAME TempCustomer = NULL; 

T henext significant part of theprogram isthesection for addi ng a record, which 
is called when the user enters the A command. First, theprogram allocates a block of 
memoryto hold thecusT name structureusingcai i oc( ) , which initializes thismemory 
to zero. (Remember, ma 1 1 oc() doesnotinitializememory.)Afterthememoryhasbeen 
allocated, theprogram prompts for the name to be added: 

case ' A' : / * Add a record */ 
case ' a' : 

Customer = ( PCUSTNAME) ca I I oc ( s i z eof ( CUSTNAME) , 
I NCREMENTAMOUNT) ; 

p r i n t f ( " E n t e r name %d: ", ++n Record); 
g et s ( s z Buf f er ) ; 
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C C C 
III] 

c cc 



szBuffer[si zeof( Customer->szName) - 1] = '\0'; 
strcpy( Customer - >szName, szBuffer) ; 

if ( s t r I e n ( C u s t o me r - >s z Na me ) > 0) 

If the user has entered aname(and not just pressed Return), this member must 
beadded tothelinked list. Thisprogram insertsmembersintothelistin sorted order. 
Your program could insert members based on another criterion, for example, Z I P code 
or customer number. 

N othing preventsyou from having two or moresets of links. You might havethe 
list linked based on customer name, Zl P code, and customer number. Each additional 
key, however, slows theprogram'sperformancewhen a record isinserted and requires 
an additional two pointers for the customer structure (the preceding pointer and the 
next pointer). When you create a linked list with more than one set of links, simply 
treat each set of links as a separate linked list. 

W hen a record isinserted into alinked list, therearefourpossiblescenarios. 0 ne, 
the list might have nothing in it, and this is the initial member. Thus, both 
Fi rstcustomer and Last Cust omer must be initialized to this member, as follows: 

{/* Insert this record in the list, sorted by name. */ 
nNeedSavi ng = TRUE; 

i f ( Fi rstCustomer == NULL) 

{ 

p r i n t f ( " I t is first record \ n " ) ; 
Customer- >Next Cust o me r = NULL; 
Customer- >Pr evCust o me r = NULL; 

F i r s t C u s t o me r = C u s t o me r ; 
L a s t C u s t o me r = C u s t o me r ; 
Temp Cust omer = NULL; 

} 

else 

{ 

T e mp C u s t o me r = F i r s t C u s t o me r ; 

} 

while ( Te mpC u s t o me r ) 
{ 

if ( n Debug) 

{ 
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pr i ntf ( "TESTI NG FOR ADD: ' %s ' ' %s ' \ n", 
Cu s t o me r ■ >s z Na me, 
Te mp Cu s t o mer - >s z Na me ) ; 

} 

I f thisisnot thelist'sinitial member, theprogram must go down thelist searching 
for the correct insertion point. The record could be inserted in three places: 

• At the beginning of thelist, as the new first member. 

• In the middle of thelist. 

• At the end of thelist, as the last member. 

H ere is the code for inserting a member at the beginning of thelist: 

if ( s t r c mp ( C u s t o me r - >s z Na me, 
Temp Cu s t o me r ■ >s z Na me ) < 0 | 
TempCust omer == LastCustomer) 

{ 

if ( strcmp( Customer - >szName, 

TempCust omer - >sz Name) < 0 && 
TempCust omer == F i r s t Cu s t o me r ) 

{ 

i f ( nDebug) 

{ 

p r i n t f ( " As s i g n i n g as f i r s t \ n " ) ; 

} 

Customer- >NextCusto mer = FirstCustomer; 

F i r s t C u s t o me r = C u s t o me r ; 

Customer- >Pr evCust o mer = NULL; 

Temp Customer = Customer- >NextCusto mer; 

TempCustomer->PrevCustomer = Customer; 

When the member will bethefirst member in thelist, theprogram updates the 
Fi r st customer variableand theold first member. T heF i rst customer variableand the 
old first member's previous member pointer (- >pr evCust omer ) point to this new 
member. The new member's previous member pointer (- >pr evCust omer ) points to 
null, and thenew member's next member pointer (- >Next customer ) points to theold 
first member (which has become the second member in thelist). 
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I n Figure 10.6, the bold lines show which pointers must be changed when a 
record is inserted in thebeginning of the list. Compare this figure with Figure 10.4. 



J 



Pointer to the 
first member 



Pointer to the i 
second member I 



Pointer to The 
third member 



Pointer to the 
nth member 



Pointer to the 
last member 





last member 








i 



Pointer back to 
he fir -Et rnernbei 



| Pointer back to 
the second 



| Pointer back to 
tie mird member 



j Pointer back to 
' He ntti rr 



_ Pointer to the 
last member 



ll 



^Pointer to NULL 



□ 



The bold lines show the changes 
made to insert a member at 
the beginning of the list. 



Figure 10.6. 1 nserting a new member at the beginning of a linked list. 



When thememberwill bethelast member in thelist, theLast cus t omer variable 
and the old last member must be updated: 

} 

el se 

{ 

if ( s t r c mp( C u s t o me r - >s z Na me , 

Te mp Cus t o mer - >s z Na me ) > 0 && 
TempCust omer == L a s t Cu s t o me r ) 

{ 

The Last cus t omer variable and the old last member's next member pointer 
(- >Nex t cu s t ome r ) will now point to the new member. The new member's next 
member pointer (- >Next customer ) will point to null, and thenew member's previous 
member pointer (- >pr evcust omer ) will point to the old last member (which has 
become the next-to-last member in thelist). 

The bold lines in Figure 10.7 show which pointers must be changed when a 
record is inserted at the end of thelist. Compare this figure with Figure 10.4. 
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Pointer to the_ 
fir'E.I member 



Pointer to the 1 
second member ' 



Pointer to the 
third member 



Pointer to the 
nth member 



Pointer to the 
last member 



Pointer to NULL « 



last member 



(Pointer bach to 
the first member 



| Pointer back to 
tie second member 



Pointer bach to 
the third member 



(Pointer bach to 
the nth member 



The bold lines show changes 
made to insert a member at 
the end of the list 



5 



New last member 
nth +2 



Pointer to tie 
" last member 



Figure 10.7. Inserting a new member at the end of a linked list. 



The third insertion point is the middle of the list. Following is the code for 
inserting a member in the middle of the linked list: 

if ( n Debug) 

{ 

pri ntf( "Assi gni ng as I as t \ n " ) ; 

} 

Cust omer - >Pr evCust omer = LastCustomer ; 

Last Cust omer = C u s t o me r ; 

Customer - >NextCustomer = NULL; 

Temp Customer = Customer- >Pr evCusto me r; 

TempCust omer - > N e x t Cust omer = Customer; 

} 

else 

{ 

i f ( nDebug) 
{ 

pri ntf("Assigni ng inside I i s t \ n " ) ; 

} 

The program must update what will be the previous customer's next member 
pointer (- >Next customer ) to point to the new member. The new member's prior 
member pointer (- >pr evCust omer ) will point to this previous customer member as 
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well. The program must also update what will be the next customer's prior member 
pointer (- >pr evcust omer ) to point to the new member. The new member's next 
member pointer (- >Ne x t customer ) will point to this next customer member as well. 

SeeFigurel0.8, which showswhatishappening when a member isinserted into 
themiddleof thelist. Thebold lines indicate which pointers must be changed when 
a record isinserted in themiddleof thelist. Compare this figure with Figure 10.4. 



Pointer to He 
first member 



Pointer to the 
second member 



Pointer to NULL 




The bold lines show the changes 
made to insert a member in 
the middle of the list 



Pointer to NULL < 





last member 











Pointer bacK to 
frie nth member 



Pointer to the 
last member 



Figure 10.8. Inserting a new member in themiddleof a linked list. 



T heuser must provide the program with other information, such astheaddress, 
city, and state. Theprogram can get misinformation after the record has been inserted 
into the list. (H owever, you could change the program so that the information is 
obtained before the record insertion.) 

Customer - >PrevCustomer = 

TempCustomer - >Pr evCustomer ; 

Customer - >NextCustomer = TempCustomer; 
TempCust omer - >Pr evCust omer = Customer; 
TempCustomer = Customer- >Pr evCust o me r; 
TempCust omer - > N e x t Cust omer = Customer; 

} 

} 

The code to display records in the list in sorted order is simple because the 
program maintains sorted links. 
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TempCust omer = Fi rstCustomer; 
pri ntf( "Di spl ay c u s t o me r s \ n " ) ; 

whi I e ( TempCust omer ) 

{ 

if ( nDebug) 

{ 

pri n t f ( 

"Name ' % 1 0 s ' Me %l p Next %l p Prev % I p \ n " , 
Te mpCu s t o me r - >s z Na me , 
TempCust omer , 

TempCustomer - >Next Cust omer , 
Te mpCu s t o me r - >Pr evCust o me r ) ; 

} 

else 

{ 

pri n t f ( 

"Name ' %1 0 s ' City %1 0 s ' State ' %2s' " 

"ZIP ' %5 . 5 d ' \ n " , 

Te mpCu s t o me r - >s z Na me , 

Te mpCu s t o me r - >s z Ci t y , 

Te mpCu s t o me r - >s z St a t e , 

TempCus t omer ■ >nZi p ) ; 

} 

TempCustomer = TempCustomer - >NextCustomer; 

} 

break; 

First, the program gets a pointer to the first member of the list and saves the 
pointer in Fi rst customer . When the first member of the linked list is obtained, it is 
displayed. The first member (and each following member, except the last one) hasa 
pointer to thenext member. Thefinal member in thelisthasa pointer to N U LL, which 
endsthewhi i eo loop. J ust beforetheend of thewh i i e( ) loop, thepointer to thenext 
customer record is assigned to TempCustomer . This allows the loop to display all the 
records. 

Theloop'soutput depends on theprogram'sdebug mode. In debug mode(used 
when the program is developed), the pointers are printed; otherwise, the names and 
addresses are printed. 
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With a linked list, it is easy to retrieve records in sorted order. Using multiple 
links, a program can retrieve records based on different criteria. A double linked list 
enables you to access the list in either forward order or backward order. 

Linked lists do create a problem, however. The only way to access a specific 
member in the list is with a linear search. Because the list's members may be located 
randomly in memory, theonlyaccessyou usually havetothelist'smembersisto follow 
thechain of links. Therefore, finding a member in themiddleof the list is not more 
efficient than finding a specific member in an unsorted list. Your program will know 
when thekey field isgreater than thememberbeingtested, withoutsearchingtheentire 
list. But you typically will be looking at approximately n/2 members (where n is the 
number of members in the list) to retrieve a specific member. 

Indexing 

U sing an index to accessdata in afileisoneway of gaining fast accessto a largefileof 
large data objects. Rarely can all of a user'sdatafit in memory at onetime, so you must 
use a file as temporary or permanent storage. 

W ith an index, theprogram'sdataisseparated into two objects: thedataand the 
index. Thedataisusually not arranged in a specific order; newrecordsareaddedto the 
end of the block or thefile. The index (there may be more than one index) is always 
sorted. It contains the minimum necessary to allow the program to access the data, 
typicallyakeyvaluethattheindexissorted on andapointertothecorrespondingdata. 

Figurel0.9showsanind exed d ata f i I e system thatconsistsof adata fileand two 
index files used to access the data. The records in this example are simple; many 
applications have thousands of bytes per record. 

Each record in the data file is 183 bytes long. Each record contains a name, a 
company name, and an ad d ress th at con si sts of thestreet, city, state, and Zl P code. T he 
two index files are an index for the namefidd and an index for ZIP codes. Note that 
you cannot predict the order of records that do not have unique ZIP codes. In this 
example, ather record with theZIP code of 03468 could have been first. 

The main factors for choosing an indexed data access system follow: 

The main data file does not need to be sorted. 

There can be more than oneindex, resulting in fast access to a given record. 
Indexes can be created "on the fly," as the need arises. 
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TheZIP codeindex in Figure 10.9 has only 13 bytes per record. These short 
recordscan be sorted more quickly than the 183-byte records that makeup theentire 
file. 

ThelNDEX.C program in Listing 10.5 creates an indexed structure. This 
program writes recordsto a data fileand retainsan index array in memory. The array 
is then used to access the records. 



Name index 



Field name 

Field length— 




Figure 10.9. An indexed data filesystem. 



Listing 10.5. INDEX. C. 



/ * I NDEX, wr i 1 1 en 1 99 2 by Peter D. Hi pson 

* This program shows indexed access to a file. It 

* has better error checking than the CDB program in 

* Chapter 8. 



#i nc 
#i nc 
#i nc 
#i nc 
#i nc 
#i nc 

#def 
#def 

#def 
#def 

#def 
#def 



u d e <sea r c h . h > 

u d e <st r i ng. h> 

u d e <ct ype. h> 

u d e <st di o. h> 

u d e <pr ocess. h> 

u d e <st d I i b. h > 

ne TRUE 1 

ne FALSE ( I TRUE) 



ne I NCREMENTAMOUNT 1 / : 

ne I N DE X_ S I ZE 4 0 0 / 

ne CUST0MER_ RECORD 1 

ne SUPPLIER RECORD 2 



Add one record at a time */ 
Ma x i mu m n u mbe r of records * / 
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/* Define the structure for the customer database. */ 



struct 



CUSTNAME ; 



typedef struct _CUSTNAME { 



i n i 


nRecordType; 


/ / 1 == Customer 


record 






struct 


_ CUSTNAME *NextCustomer ; // Lin 


k to next 


, or NULL if 


none 


struct 


_ CUSTNAME *PrevCustomer ; // Lin 


k to p r e v 


i o u s , or NULL 


if none 


char 


s z N a me [ 61] ; 


// 60 chars for 


n a me ; If 


or null at en 


d 






/ / In s o me cases 


, you wo u 


1 d not need t 


0 






/ / duplicate t h i 


s field i 


n both the in 


dex and 






/ / the record. 








char 


szAddr 1[ 61] ; 


/ / 60 chars for 


address; 


1 for null at 


end 


char 


s z Ad d r 2 [ 61] ; 


/ / 60 chars for 


address; 


1 for null at 


end 


char 


szCi t y [ 2 6 ] ; 


// 25 chars for 


city; 1 f 


or null at en 


d 


char 


szSt at e[ 3] ; 


// 2 - char state 


abbr evi at 


ion plus null 




long 


1 Zi p; 


/ / Use integer. 


Print as 


%5 . 5 d for lea 


di ng 0 


i nt 


n Rec o r d Nu mbe r ; 


/ / Wh i c h record 


n u mb e r ? 






doubl e 


dSal esTot al ; 


/ / A mo u n t the c u 


s t o mer has purchased 





} CUSTNAME; 

typedef CUSTNAME 
typedef CUSTNAME 
typedef CUSTNAME 



far 
near 



: F PCUSTNAME; 
: NPCUSTNAME; 
: PCUSTNAME ; 



typedef struct J NDEXREC { 

char s z N a me [ 61] ; // 60 chars for name; 1 for null at end 
long Customer; // Pointer to customer record in file 

} CUSTI NDEX; 



typedef CUSTI NDEX far 
typedef CUSTI NDEX near 
typedef CUSTI NDEX 



FPCUSTI NDEX; 
: N P C US T I NDEX; 
: P C U ST I NDEX; 



void Gi veHel p( voi d) ; 

int compare( const void *, const void *). 



continues 
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Listing 10.5. continued 
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void 
{ 



ma i n ( ) 



FILE 
FILE 



1 Dat a F i I e; 
! I nd ex F i I e ; 



PCUSTNAME Fi rstCustomer = NULL; 

PCUSTNAME Last Cust omer = NULL; 

PCUSTNAME Customer = NULL; 

PCUSTNAME TempCust omer = NULL; 



PCUSTI NDEX Cust I ndex = NULL; 

PCUSTI NDEX pTempCustl ndex = NULL; 

CUSTINDEX TempCust I ndex; 

char szl ndexFi I e[ 257] ; 

char szDataFi I e[ 2 5 7] ; 

char sz Buf f er [ 2 5 7] ; 

/* Strings for _ s p I i t pa t h ( ) , which parses a fi 

char szDr i ve[ _MAX_DRI VE] ; 

char szDi r [ _MAX_DI R] ; 

char s z F n a me [ _ MAX_ F NAME ] ; 

char szExt [ _ MAX_ EXT] ; 



e n a me * / 



nt 
nt 
nt 
nt 
nt 
nt 



n Des i r ed Rec o r d ; 
n No t Done = TRUE; 
nRecor d =0; 
nDebug = FALSE; 
nNeedSavi ng = FALSE; 



long I Fi I ePos i t i on; 

double dSales = 0.0; /* Forces the loading of floating-point support 

*/ 
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Custlndex = ( PCUSTI NDEX) c a I I o c ( s i z e of ( C USTI NDEX ) , I NDEXSI ZE) ; 

if (Custlndex == NULL) 
{ 

fpri ntf(stderr, "Couldn't allocate necessary index memory!\n"); 
exi t ( 16) ; 

} 

memset ( Cust I ndex, 0, s i z eof ( CUSTI NDEX) ) ; 

Customer = ( PCUSTNAME ) c a I I o c ( s i z eof ( CUSTNAME ) , I NCREMENTAMOUNT) ; 

if ( Cust omer == NULL) 

{ 

fprintf(stderr, "Couldn't allocate necessary record memory!\n"); 
exi t ( 16) ; 

} 

pr i ntf ( 

"Please enter customer save file n a me - \ n " 
"Extensions of .DAT and . I N D will be used: "); 

gets( szBuffer) ; 

_splitpath(szBuffer, 
s z D r i v e , 
s z Di r , 
s z F n a me , 
szExt ) ; 

strcpy(szl ndexFi I e, szDrive); 
strcatfszl ndexFi I e, szDir); 
strcatfszl ndexFi I e r szFname); 
st r cat ( szl ndexFi I e, " . I ND" ) ; 

s t r c py ( s z Dat a F i I e, s z D r i v e ) ; 

s t r c a t ( s z Da t a F i I e , s z Di r ) ; 

s t r c a t ( s z Da t a F i I e , s z F n a me ) ; 

s t r c a t ( s z Da t a F i I e , ".DAT"); 
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Listing 10.5. continued 



DataFile = f open ( s z Dat aF i I e, "wb"); 



if ( DataFi I e == NULL) 

{/* Test for file open. If file can't be opened, exit with message. 

*/ 

printf(" ERROR: Data file ' %s ' couldn't be opened. \ n", 
s z Da t a F i I e ) ; 



exi t ( 4) ; 

} 

f cl ose( DataFi I e) ; 

IndexFile = fopen(szl ndexFi le, "wb"); 
if (IndexFile == NULL) 

{/* Test for file open. If file can't be opened, exit with message. 

*/ 

p r i n t f ( " ERROR: Index file ' %s ' couldn't be opened. \n", 
szl ndexFi I e) ; 



exi t ( 4) ; 



fcl ose(l ndexFi I e); 



p r i n t f ( " De mo of an indexed f i I e/ ar r ay. \ n" 

\ n" 

Co mma n d s a r e : \ n " 



Add a customer/supplier record. \n" 
Display current list (from file). \n" 
Exit from program. \ n" 
Toggle debug mode.\n" 
Display the co mma n d I i s t . \ n " 
Display the co mma n d I i s t . \ n " 



\n" 



n Rec o r d = ■ 1 ; 



372 



Data Management: Sorts, Lists, and Indexes 




while ( n Not Do n e) 

{ 

pri ntf("Enter c o mma n d ? " ) ; 

get s ( sz Buf f e r ) ; 

s wi t c h( s z Buf f er [ 0] ) 
{ 

case ' H' : / * Give some help */ 
case ' h' : 
case ' ? ' : 

G i v e He I p ( ) ; 

break; 

case ' A' : / * Add a record * / 
case ' a' : 

me ms et ( Cu s t o me r , 0, si zeof ( CUSTNAME) ) ; 

pri ntf( "Enter name %d: ", + + nRecord); 
get s ( s z Buf f e r ) ; 

szBuffer [ si zeof ( Cust omer - >szName) ■ 1] = '\0'; 
s t r c py ( Cu s t o me r - >s z Na me , szBuffer); 

if ( s t r I e n ( C us t o mer - >s z Na me ) > 0) 

{/* Insert this record in the list, sorted by name. */ 
nNeedSavi ng = TRUE; 

/ / Add t o f i I e and i ndex: 



C u s t o me 



r->nRecordNumber = nRecord; 



if ( I nDebug) 



do 



pri n t f ( " Enter 1 for customer, 2 for supplier \ 
"); 



continues 
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gets(szBuffer); 

s s c a nf ( s z Buf f er , "%d", &Customer- 
>n Re c o r dType) ; 

} 

while ( Customer - >nRecordType != CUSTOMER_ RECORD 
&& 

Cust omer - >n Reco r d T y pe != SUPPLIER RECORD); 



Listing 10.5. continued 



p r i n t f ( " Enter address I 
gets(szBuffer); 
szBuffer[ si zeof ( Custome 
s t r c py ( Cus t o mer - >sz Add r 



i n e 1 : " ) ; 

r - >s z Ad d r 1 ) - 1] = ' \ 0' ; 
1, szBuffer); 

2: "); 

z Ad d r 2 ) - 1] = ' \0' ; 
z Buf f er ) ; 



zCi ty) - 1] = '\0'; 
Buffer); 



printf(" Enter address line 
gets(szBuffer); 
szBuffer[ si zeof ( Customer - >s 
s t r c py ( Cus t o mer - >sz Add r 2, s 

pri ntf( "Enter City: " ) ; 

gets(szBuffer); 

szBuffer [ si zeof ( Customer - >s 

s t r c py ( Cus t omer - >sz Ci t y , s z 



pri n t f ( " Enter state postal abbreviation: "); 
gets(szBuffer); 

szBuffer! si zeof ( Customer - >szState) - 1] = '\0'; 
s t r c py ( Cus t o mer - >sz St at e, szBuffer) ; 

pri ntf( "Enter ZIP code: " ) ; 
gets(szBuffer); 

sscanf ( szBuffer , "%d", &C u s t o mer - >nZi p) ; 

pri ntf( "Enter total sales: " ) ; 
gets(szBuffer); 

sscanf ( szBuffer , "%f", &C u s t o me r - >d Sa I es Tot a I ) 



Data File = f o pe n ( s z Dat a F i I e , "ab"); 
if ( DataFi I e == NULL) 
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p r i ntf ( 

"ERROR: Dat a file ' %s ' couldn't be " 
"opened for update. \ n " , 
sz Dat aF i I e) ; 

exi t ( 4) ; 

} 

f seek( DataFi I e, 0, SEEK_ END) ; 

Custl ndex[ nRecord] . Customer = ftel I (DataFi I e); 
strcpy(Custl ndex[ nRecord]. szName, Customer->szName); 

pri ntf( "I ndex %d ' %s ' is at ' %l d ' \ n " , 
nRecord, 

Cust lndex[ nRecord]. szNa me, 
Cust I ndex[ nRecord] . Customer ) ; 

f wr i t e( Cust omer , si zeof ( CUSTNAME) , 1, DataFi I e ) ; 

f c I os e( Dat a F i I e ) ; 

} 

el se 

{ 

pri ntf( "\aSorry, name must not be b I a n k ! \ n " ) ; 

} 

break; 

case ' T : I* Debug mode toggle */ 
case ' z ' : 

n Deb u g = ! n Deb u g ; 

break; 

case 'D': /* Display a record */ 
case ' d' : 

pri ntf( "Di spl ay customer (total %d).\n", nRecord + 1); 

qsor t ( Cust I ndex, 
nRecor d + 1, 
si zeof ( CUSTI NDEX) , 
c o mp a r e ) ; 
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Listing 10.5. continued 



for (i = 0; nDebug && i <= nRecord; i + + ) 

{/* In debug mode, display the sorted index list. */ 
p r i n t f ( " R e c o r d %2 d s z N a me ' %s ' \ n " , 
i , 

Cust I ndex[ i ] . szName); 

} 

me ms et ( Cu s t o me r , 0, s i z eof ( CUST NAME )) ; 

me ms et ( &TempCus 1 1 ndex, 0, si zeof ( CUSTI NDEX) ) ; 

pri ntf("Enter n a me " ) ; 

get s ( TempCus 1 1 ndex . s z Na me) ; 

pri n t f ( " Searching with a linear search\n"); 

n Des i r ed Rec o r d = - 1 ; 

for ( i = 0 ; i <= n Re c o r d ; i + + ) 
{/* Linear search; could be bsearch() */ 
if ( s t r i c mp ( T e mp C u s 1 1 ndex. s z N a me , 
Cust I ndex[ i ]. szName) == 0) 

{ 

n Des i r ed Rec o r d = i ; 
break; 

} 

} 

if ( n De s i r ed Rec or d >= 0 ) 

{ 

Data File = f o pe n ( s z Da t a F i I e , "rb"); 

if ( DataFi I e == NULL) 

{ 

pr i ntf ( 

"ERROR: Dat a file ' %s ' couldn't be \ 
opened. \ n " , 
s z Dat a F i I e) ; 
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exi t ( 4) ; 

} 

f s e e k ( DataFi I e, 

Cust I ndex[ nDesi redRecord] . Customer, SEEK SET) ; 

f r ead ( Cust omer , si z eof ( CUST NAME ) , 1, DataFi I e ) ; 

pr i nt f ( 

"Name ' %1 0 s ' Ci ty ' %1 0 s ' State ' %2s' " 

"ZIP ' %5 . 5 d ' \ n " , 

Cu s t o me r - >s z Na me, 

Cust o me r - >s z Ci t y , 

Cust omer - >szState, 

C u s t o me r - >n Zi p) ; 

f ci ose( DataFi I e) ; 

} 

el se 
{ 

pr i ntf ( " LI NEAR SEARCH: Sorry, the name ' %s ' couldn't \ 
be f o u n d \ n " , 
TempCust I ndex. szName) ; 

} 

p r i n t f ( " Searching with a binary search \ n") ; 

if ( ( pTempCust I ndex = ( PCUSTI NDEX) bsearchf &TempCust I ndex, 
Cust I ndex, 
n Rec o r d + 1 , 
si zeof ( CUSTI NDEX) , 
compare) ) I = NULL) 

{ 

DataFi I e = f o pe n ( s z Da t a F i I e , "rb"); 

if ( DataFi I e == NULL) 
{ 

pr i ntf ( 

"ERROR: Dat a file ' %s ' couldn't be \ 
opened. \ n " , 
sz Dat aF i I e) ; 
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Listing 10.5. continued 



exi t ( 4) ; 

} 

f s e e k ( DataFi I e, 

pTempCust I ndex - >C u s t o me r , SEEK_SET) ; 

fread(Customer, si zeof ( CUST NAME ) , 1, DataFi I e ) ; 

pr i n t f ( 

"Name ' %1 0 s ' Ci ty ' %1 0 s ' State ' %2s' " 

"ZIP ' %5. 5d' \n", 

C u s t o me r - >s z Na me , 

Cust o me r - >s z Ci t y , 

Cust o mer - >s z St a t e, 

Cus t o me r - > n Z i p) ; 

fcl ose( DataFi I e) ; 

} 

else 

{ 

pri ntf("BSEARCH: Sorry, the name ' %s ' couldn't be \ 
f o u n d \ n " , 
TempCustl ndex. szName) ; 

} 

break; 

case 'X': /* Exit; prompt for save if needed. */ 
case ' x' : 

n No t Done = FALSE; 

szBuffer[0] = '\0'; 

while ( n Need Sa v i n g && 
szBuffer[0] == '\0' ) 

{ 

pri ntf("\nSave the data? ( y | n ) " ) ; 
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gets( szBuffer ) ; 

if (szBuffer[0] == 'n' 
szBuff er[ 0] == ' N' ) 

{ 

nNeedSavi ng = FALSE; 

} 

else 

{ 

if ( szBuffer [ 0] ! = ' y' && 
szBuf f er [ 0] ! = ' Y' ) 

{ 

printf("\nWrong a n s we r , " 

"please respond wi t h ' y' or ' n' ") ; 

szBuf f er [ 0] = ' \ 0' ; 

} 

} 

} 

if ( ! nNeedSavi ng) 

{/* Don't need to save, so just exit */ 
break; 

} 

/* Else fall through to the save routines */ 

case ' S' : / * Save all records */ 
case ' s ' : 

pri ntf( "Savi ng c u s t o me r index f i I e . \ n " ) ; 
IndexFile = fopen(szl ndexFi I e r "wb"); 
if (IndexFile == NULL) 

{/* Test for file open. If file can't be opened, exit 
wi t h message. */ 

pri ntf( "ERROR: Index file ' %s ' couldn't be \ 
opened. \ n " , 
szlndexFile); 
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Listing 10.5. continued 

} 

else 

{ 

fwri te(Custlndex, 

si zeof ( CUSTI NDEX) * ( nRecor d + 1) , 
1, 

I ndexFi I e) ; 
f cl o s e ( I ndexFi I e) ; 
nNeedSavi ng = FALSE; 

} 

break; 
default: 

printf("\aUnknown operation '%c'\n", 

s z B u f f e r [ 0 ] ); 
break; 

} 

} 

} 



i n t c o mp a r e ( 

PCUSTI NDEX Cust I ndexl, 
PCUSTI NDEX Cust I n d e x 2 ) 

{ 

// Un comment the following printf() to see how qsort and qsearch work. 

/ / p r i n t f ( " C o mp a r i n g %s and %s \ n " , 
/ / Cu s 1 1 n d ex 1 - >s z Na me , 

/ / Cu s 1 1 n d ex 2 - >s z Na me ) ; 

r et u r n ( s t r i c mp ( 

( ( PCustl ndex) Custl ndexl) - >szName, 
((PCustl ndex) Custl ndex2)->szName)) ; 

} 
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void Gi veHel p( ) 



pr i ntf ( 

" \ n " 

"This program shows how an indexed file list is created a n d \ n " 
"used. It enables you to add records, display a speci f i ed \ n" 
"record, and save the list of records to the disk file.\n" 

" \ n " 

"INDEX supports the following c o mma n ds : \ n " ) ; 



pr i ntf ( 

" \ n " 

A - Add a c u s t o me r / s u pp I i e r record.\n" 

Adds a record. Each added record is placed\n" 
in the list in the correct order.\n"); 



p r i nt f ( 

" \ n " 

D - Display current list.\n" 

Prints the user-specified record. This\n" 

c o mma nd lists the name and address\n" 

information, a s s u mi n g the name has been found. \ n") ; 



p r i nt f ( 

"\n" 

X - Exit from program. \ n" 

Ends the program. If records or the index have\n" 
not been saved, will prompt for save. All saves \ 
a r e \ n " 

made to the file specified when the program was \ 
started. \ n"); 



p r i nt f ( 

"\n" 

Z - Toggle debug mo de.\n" 

Changes the information displayed for the\n" 
user. When on, debug mode shows the sorted\n" 
index list. \n"); 



continues 
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Listing 10.5. continued 



p r i n t f ( 

"\n" 

? - Display the co mma n d I i s t . \ n " 
H - Displaytheco mma n d I i s t . \ n " 

Displays this help i n f o r mat i o n . \ n " ) ; 

p r i n t f ( 

"\n" 

S - Save the list.\n" 

If records and the index have not been saved, this \ 
opti on\ n" 

saves the records the user has entered. All saves \ 
are ma d e \ n " 

to the file specified when the program was \ 
started. \n"); 

p r i n t f ( 

"Additional feature: In this program includes a prompt\n" 
"to save when the exit command is given. (This prompt\n" 
"is given only when the records have not been saved since\n" 
"the last added r e c o r d ) . \ n " ) ; 

p r i n t f ( 

"Additional feature: This program has a debug mode so t h a t \ n " 
"the user can see how the program works. This debug mode \ 
a I I o ws \ n " 

"the user to print the linked list and its pointers. \ n " ) ; 

} 



First thecusTNAME structure (which is identical to the structure used in many of 
the other example programs) is defined. Then an index on the customer's name is 
defined. 

In general, thefield you are indexing on should be unique (although this is not a 
requirement). When you usetheindexto retrieve records, a uniquefield ensures that 
only one name is returned for each requested search, which can make your program 
simpler because is does not have to process multiple matches. 
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The definition of theindex structure follows: 



t ypedef struct _ I NDEXREC { 
char s z Na me [ 6 1 ] ; 
long C u s t o me r ; 
} CUSTI NDEX; 



// 60 chars for name, 1 for null at end. 

// Pointer to actual customer record in file. 



typedef CUSTI NDEX far * F P C US T I NDEX; 
typedef CUSTI NDEX near * NPCUSTI NDEX; 
typedef CUSTI NDEX * P C U ST I NDEX; 



Pointers are defined for the structure, like any other typedef 'd structure. A 
c o mp a r e ( i function isalso defined for usewhen sorting (and searching) theindex. T he 
advantage of an indexed file is that it is always sorted. H owever, you can avoid re- 
sorting the entire index when arecord isadded or an index field ischanged. A typical 
trick is to retain the existing records in the sorted index, and when arecord isadded 
or changed, add ittoaspecial areaattheend of theindex. If a binary search ofthesorted 
portion of the index does not find the record, a linear search is used on the special 
section of nonsorted records. When the count of records in the unsorted section 
exceeds a predetermined value, the program re-sorts the index. 



Linear Search Versus Binary Search 

A linear search starts with thefirst record in the list or file, and reads each 
record until it finds a match to the key or the file ends. In a linear search, the 
list or file does not need to be sorted, and the records in the list do not have 
to be in any particular order. 

A binary search proceeds as follows: 

1. The binary search starts with the middle item in the list. If the key is less 
than the selected item, the binary search takes the item halfway between 
the current item and the beginning of the list. If the key is greater than 
the selected item, the binary search takes the item halfway between the 
current item and the end of the list. With one comparison, the binary 
search eliminates half of thefile. 

2. If the key is less than the item found in step 1, the half less than theitem is 
selected. If the key is greater than theitem found in step 1, the half that is 
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greater than the item is selected. 0 f this half, the middle item is then again 
selected. 

3. This process is repeated until a match is found or it is shown that the key is 
not part of the list. 

For example, suppose the key (the item you want to find) is 5. Your list 
contains the following numbers: 1, 2, 5, 12, 23, 24, 34, 35, 38, 45, 47, 50, 
60, 65, 66, 76, 78, and 80. The first selection is 38 (the middle item in the 
list). Because 5 is less than 38, the next selection is 23, (halfway between 1 
and 38). Because 5 is smaller than 23, the next selection is 5 (halfway be 
tween 1 and 23). This is a match, so the search stops. 

The maximum number of comparisons with a binary search is small— in a 
file of 65,000 items, at most only 16 comparisons must be made. With a 
linear search, an average of 32,000 comparisons are required. 

Thewinner?A binary search is always the winner when the list can be(or is) 
sorted. If the list cannot be sorted, a linear search must be performed. 



Fortunately, theC compiler providesa binary search function called bsearcM ) . 
This function requires a sorted list and the address of a compare function. The 
bsear cm ) and bsor t ( ) functions use the same compare function, so that only one 
com paref unction needs to be written when using either bs ea r c h ( ) or bs o r t ( ) . In our 
sorting and search i n g, we are worki n g wi th an array of i n dex records, an d th ese i n dex 
records are what must be dealt with by the compare function. Because with bsor t { ) 
and bsearchi i the compare ispassed theaddressof the array members, the compare 
function is defined as accepting two pointers to custi ndex structures. 

int compare( const void *, const void*); 

W hen theuser wants to add a record to thecustomer database, theprogram first 
usesmemset ( ) toclear thecust omer structure. 1 1 then promptsforthename. If theuser 
enters a name, the program processes it. 

The code for adding a record follows: 

case ' A' : / * Add a record * / 
case ' a' : 
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memset ( Cust omer , 0, si z eof ( CUST NAME ) ) ; 

pri ntf( "Enter name %d: ", + + nRecord); 
get s ( s z Buf f e r ) ; 

s z Buf f er [ s i z eof ( C u s t o me r - >s z Na me) ■ 1] = '\0'; 
s t r c py ( Cus t o mer - >sz Na me , s z Buf f er ) ; 

if ( s t r I e n ( C us t o mer - >s z Na me ) > 0) 

{/* Insert this record in the list, sorted by name. */ 
nNeedSavi ng = TRUE; 



To add the record to thedatabase, theprogram first opensthedatabasefile. The 
fileisclosed when it isnotin usesothatthedatabaseisassafeaspossibleif thecomputer 
fails. If you do not close files in your program, you should at least call ff i us h{ ) after 
every write to the file. 

Thefileisopened in theappend modesothatexistingrecordsarenotlost. If the 
filewereopened in thewritemode, theoperating system would delete thecontentsof 
the file. 

Dat a F i I e = f o pe n ( s z Da t a F i I e , " a b " ) ; 

i f ( Dat a F i I e == NULL) 

{ 

pri nt f ( 

"ERROR: Data file' %s ' coul d n ' t be " 
"opened for update. \ n", 
s z Da t a F i I e ) ; 

exi t ( 4) ; 

} 

After thefileisopened, theprogram goes to theend of thefile: 

fseek( DataFi I e, 0, SEEKEND) ; 

Thet tei i ( i function returnsthecurrent filepointer for therecord that will be 
added. Thisvalueisassigned to the i ndex array's poi n ter to th is record . Next, st r cpy( ) 
copies the key i nto the index array: 



// 



Add to file and index: 



Customer - >nRecordNumber = nRecord; 
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Cust I ndex[ nRecord] . Customer = ftel I ( DataFi I e) ; 
strcpy(Custl ndex[ nRecord] . szName, Customer - >szName) ; 

After theindex has been set up, theprogram writestherecord tothedatabaseand 
closes the file: 

f wr i t e( Cust o mer , si zeof ( CUSTNAME) , 1, DataFi I e ) ; 
f cl ose( DataFi I e) ; 

W hen theuser requests a record, theprogram searchesfor therecord using both 
a linear search and the bs ear cm ) function. I used both search techniques in List- 
ing 10.5 simply to show how they are implemented; your program should useoneor 
the other (probably bs ear cm ) because it is easy to implement and fast). 

T o u se a bi n ary search , th e i n dex m u st be sorted . W h en th e user wan ts th e n am es 
displayed, theprogram sorts the index list. The programmer can choose to sort the 
index either as names are added (which slows the process of adding names) or when 
thesorted index list is used. This program would have been better if it included a flag 
to indicate when the list was already sorted. 

Thefollowing code shows how a record is retrieved and displayed: 

case 'D': /* Display a record */ 
case ' d' : 

pr i n t f ( " Di s pi ay customer (total %d).\n", nRecord + 1); 

qsor t ( Cust I ndex, 
nRecord + 1 , 
si zeof ( CUSTI NDEX) , 
c o mp a r e ) ; 

for (i = 0; nDebug && i <= nRecord; i ++) 
{/* In debug mode, display the sorted index list. */ 
pr i n t f ( " Rec o r d %2d szName '%s'\n", 
i , 

Custl ndex[i ] . szName); 

} 

In thedebug mode, theprogram first shows the programmer theindex list. This 
display is useful when you want to see the results of the sort. 
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Following the display of the index list, the user is prompted to provide a name 
to search for: 

me ms et ( Cu s t o mer , 0, si zeof ( CUSTNAME) ) ; 

me ms e t ( &Te mp Cus t I n de x , 0, s i zeof ( CUSTI NDEX) ) ; 

pri ntf( "Enter n a me " ) ; 
gets(TempCustlndex.szName); 

pri ntf( "Searchi ng with a linear search\n"); 

Af ter th e u ser en ters a n ame, th e p rogram does a I i n ear search .This search starts 
atthefirst name, then searcheseach namein order, until either thelistendsorthename 
is found: 

nDesi redRecord = ■ 1 ; 

for ( i = 0 ; i <= nRecord; i ++) 
{/* Linear search; could be bsearch() */ 
i f ( s t r i c mp ( T e mp C u s 1 1 n d e x . s z N a me , 
C u s 1 1 n d e x [ i ] . szName) == 0) 

{ 

n Des i r ed Rec o r d = i ; 
break; 

} 

} 

If the supplied key name is found, the program opens the database file (read 
mode) and uses f seeM ) to find the correct record. After finding the record, the 
program readsitin and displays theinformation fortheuser. Ifthesupplied keyname 
is not found, theprogram simply gives theuser a message that thename wasn't found. 

if (n Desired Record >= 0) 

{ 

Dat a F i I e = f o pen ( s z Da t a F i I e , " r b" ) ; 

if ( DataFi I e == NULL) 

{ 

pri n t f ( 

"ERROR: Data file ' %s ' couldn't be opened. \n", 
s z Da t a F i I e ) ; 
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exi t ( 4) ; 

} 

fseek( DataFi I e, 

Custl ndex[ nDesi redRecord] . Customer, SEE K_ SET); 

fread(Customer, si zeof ( C UST NAME ) , 1, DataFi I e ) ; 

p r i n t f ( 

" Name ' %1 0 s ' City ' %1 0 s ' State ' %2s ' " 

"ZIP ' %5 . 5 d ' \ n " , 

Cust omer - >sz Name, 

C u s t o me r - >s z Ci t y , 

Customer - >szState, 

Cust omer - >nZi p) ; 

fcl ose( DataFi I e) ; 

} 

else 
{ 

pri ntf( "LI NEAR SEARCH: Sorry, the name ' %s ' couldn't be found\n", 
Temp Cust I ndex. szName) ; 

} 

After thelinear search isfinished, theprogram doesa binary search. Thissearch 
is performed with one statement: 

if ( ( pTempCust I ndex = ( PCUSTI NDEX) bsearchf&TempCust I ndex, 
Cust I ndex, 
n Rec o r d + 1 , 
s i zeof ( CUSTI NDEX) , 
compare) ) ! = NULL) 

{ 

If the supplied key name is found, theprogram opens the database file (read 
mode) and uset seeM ) to find the correct record. After seeking to the record, the 
program readsit in and displays the information fortheuser. If thesupplied keyname 
is not found, the program displays a message that the name wasn't found. 

DataFile = fopenfszDataFile, "rb"); 

if ( DataFi I e == NULL) 
{ 
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pr i ntf ( 

"ERROR: Data file ' %s ' couldn't be opened. \n", 
s z Da t a F i I e ) ; 

exi t ( 4) ; 

} 

f seek( Dat a F i I e, 

pTempCust I ndex - >Customer , SEE K_ SET); 

f r ea d ( Cust omer , si zeof ( CUSTNAME) , 1, DataFile); 

pr i ntf ( 

"Name ' %1 0 s ' City %1 0 s ' State ' %2s' " 

"ZIP ' %5. 5d' \ n", 

Cust omer - >sz Name, 

Cus t o mer - >s z Ci t y , 

Cus t o mer - >s z St at e, 

Cust omer - >nZi p) ; 

f c I o s e( Dat a F i I e) ; 

} 

el se 

{ 

pr i ntf ( " BSEARCH: Sorry, the name ' %s ' couldn't be found\n", 
TempCust I ndex. szName) ; 

} 

break; 

W hen the program ends (or when the user requests a save), the index array is 
saved to a file. The index array in the saved file could be re-read into the index array 
later when the user reuses the data file. To conserve on disk space, the program writes 
only the index entries that have been used, not the entire index array. 

case ' S' : / * Save all records */ 
case ' s' : 

pri ntf( "Savi ng c u s t o me r index f i I e . \ n " ) ; 
IndexFile = fopen(szlndexFile, "wb"); 
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if ( I ndexFi I e == NULL) 

{/* Test for file open. If file can't be opened, exit with message. 

*/ 

p r i n t f ( " ERROR: Index file ' %s ' couldn't be opened. \n", 
szl ndexFi I e) ; 

} 

else 
{ 

fwri t e ( C u s 1 1 ndex, 

si zeof ( CUSTI NDEX) * ( nRecor d + 1) , 
1, 

I ndexFi I e) ; 
fcl ose( I ndexFi I e) ; 



nNeedSavi ng = FALSE; 

A quick look at the compare function shows that the s z Na me members of the 
index array are being compared using s t r i cmp( ) . I haveincluded a (commented out) 
pri ntf ( i that shows how the sort and thesearch use thecompare function. 

i n t c o mp a r e ( 

PCUSTI NDEX Cust I ndexl, 
PCUSTI NDEX Cust I ndex2) 

{ 

// Un comment the following pri ntf () to see how qsort and qsearch work. 

/ / p r i n t f ( " C o mp a r i n g %s and %s \ n " , 
/ / Cu s 1 1 n d ex 1 - >s z Na me , 

// Custlndex2->szName); 

r et u r n ( s t r i c mp ( 

Cust I ndexl - >szName, 
Custlndex2->szName)); 

} 

Indexes can reside permanently in a disk file. Theindex for large databases can 
be much too large to fit into memory. To search a disk-based index, you must write 
a binary search function. Typically, such afunction would know— by a global variable 
or a passed parameter— the number of records in the index, the size of the index 
records, and the index file's name or file handle. 
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Your disk-based bsearch function would then read themiddlerecord. Compute 
this record's position using an f seeM ) . For example: 

/* The code assumes that more than one record is in 

* the index file. 

*/ 

long IFirstRecord = 0; 

long ILastRecord = I Total Records; 

long I Cur rent Record = ((ILastRecord - IFirstRecord) / 2); 

long lOffset = ILastRecord - IFirstRecord; 

whi I e( I Offset > 0) 

{ 

I Cur rent Record = ((ILastRecord - IFirstRecord) / 2); 

fseek( I ndexFi I e, I Cu r r e n t Re c o r d * 

si zeof ( CUSTI NDEX) * ( I Cu r r e n t Re c or d ) , SEEKSET) ; 

// Read the record into Index (not shown) 

if (Key < Index) /* This compare depends on Key's data type */ 
{ 

ILastRecord = ICurrentRecord; 

} 

if (Key > Index) /* This compare depends on Key's data type */ 

{ 

IFirstRecord = ICurrentRecord; 

} 

if (Index == Key) /* This compare depends on Key's data type */ 

{ 

r e t u r n ( I Cur rent Recor d) ; 

} 

I To t a I Re c o r d s = ILastRecord - IFirstRecord; 
I Of f s et = ILastRecord - IFirstRecord; 
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/* The record was not found! */ 
return ( - 1 ) ; 

Thisbinary search function issimplified. I did notshowthereadingoftheindex 
file, nor arethecomparesaccuratebecausetheyassumethati ndex andKey arenumeric, 
which may not be true. 

I ndexing afilecan greatly enhance the access to specific records, especially when 
a record must be accessed using more than onekey (or index) value. 

Fixed-field Disk Files 

Thebest examples of fixed-field disk files are files created using a structure. Because 
the structure's length is fixed and each member's location is known, you can al- 
ways determine the location of any structure and its members in thefile. 

I recommend reading a file written with a structure into an identical structure. 
After the data is placed in the structure, you can work on it using the individual 
structure members. A possible exception to the reading of individual records is when 
a large block of thefile is read into a structure array, and the array is searched for the 
correct key or another data object. 

M anyof theexampleprogramswritefixed-fidd files. For example, thel N D EX.C 
program (Listing 10.5) creates two fixed-field files. 



B -trees 

Noneof thedatamanagementtechniquesin this chapter have addressed theproblem 
of a data list that changes frequently, must be searched quickly, and is too large to 
constantly re-sort. Some problems with the techniques covered so far include: 

• A linked list presents data that appears to be sorted, but the list can be searched 
only with a linear search. 

• An indexed list is easy to search, but it must be resorted when an index value is 
added, deleted, or changed. 

Thesolution isto use the B-tree technique, a different method of storing data. 
T he B-tree technique arranges data in a structured format. Figure 10.10 shows some 
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sample data (used also in the "Linear Search Versus Binary Search" sidebar), and its 
organization in a B-tree. 



Figure 10.10. A B-tree's organization. 

Data organization in a B-tree resembles an upside down tree. Usually, thefirst 
data object hasa key that half of theremaining data keysareless than (called theleft 
side) and theother half of thedata keys aregreater than (called theright side). Thetree 
continues in the same manner for all remaining data objects. 

The following terms are used when discussing B-trees: 

N ode A data item in a B-tree. 

Root node Thefirst node in a B-tree. 

Left side Data items on theleft side are less than the current 




data list 
1 45 



2 47 

5 50 

12 60 

23 65 



6 6 



34 

3 5 
3 8 



76 
78 
BO 



data item. 



Right side Data items on the right side are greater than the 

current data item. 



Balance H ow well thetree is organized. (M ost B-trees exhibit 

some imbalance.) 



Figure 10.11 shows these terms and their relationships. 
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Root node 



Root node's 



Root node's 



Node 12's 
left side^ 




Node 65 is right 
child of node 50 
and parent of 
node 76 



Figure 10.11. B-tree terms and relationships. 

B-trees present some problems to the programmer, such as the following: 

As records are added to the tree, it must be reorganized to ensure that each 
node has a balanced number of data objects on its right and left sides. 

W hen a B-tree member is changed or deleted, the tree must be reorganized 
to eliminate theholethat iscreated. This reorganization can be complete, 
which rebalances the tree, or partial, which may create a dummy member to 
take the place of the missing member. 

When sorted data objects are added to the B-tree, the tree's balance suffers 
unlessthetree is reorganized. 

When programming a B-tree implementation from scratch, you must have the 
following functionality: 

Add Rec o r d ( ) Adds a record to the B-tree. I f a record with 



the key being added exists, you must decide 
what action to take: add the record as a 
duplicate record, have and increment an 
occurrence counter, or do not add the dupli- 
cate record. 



Del et e Re c or d ( ) 



Deletes a record in the B-tree. The B-tree 
must be reorganized, or a dummy record must 
be inserted to replace the deleted record. 
U sing a dummy record usually implies that 
there is a deleted flag field. 
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Sear c h Re c or d ( ) 



P r i n t Tr ee ( ) 



Searches for a key value and returns the 
information necessary to access the record. 
This function could return the record struc- 
ture if desired. 

Debugging tool. This function isneeded if 
you are creating your own B -tree functions, 
but is normally not used in a final program. 



There area number of supporting functions as well. These functions are not 
always present in any specific B-tree implementation. 

Listing 10.6, theBTREE.C program, implements a basic B-tree structure. The 
program contains the following functions: 

Finds a record in the B-tree. 



Search! ) 
Sear c h A n d Ad d ( ) 

Insert!) 
Co py I tern) ) 
Newl t em( ) 
Tr eePr i nt ( ) 
Del et el tern) ) 
Under Fl ow( ) 

Delete)) 

Pr i nt Hel p( ) 



Finds a record in the B-tree; if the key does 
not exist, the record is added. 

I nserts a record into the B-tree. 

C opies a node to another node. 

Creates a new node. 

Prints the current tree. 

D eletes a node from the current B-tree. 

U sed by Dei et ei t em( ) to adjust the B-tree 
when an item has been deleted. 

U sed by De i e t e 1 1 e m( i to delete items from 
the B-tree. 

Prints a help screen. 



Listing 10.6. BTREE.C. 



/* BTREE.C 

* This is a simple B-tree program. It should be compiled 

* under ANSI C. 

* [ BTREE. C of j UGPDS Vol . 19] 

*/ 



continues 
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Listing 10.6. continued 


#i n c 1 ude <st dl i b. h> / 


/ For 


standard functions 


#i n c 1 ude < s t d i o . h > / 


/ Make 


includes first part of file 


#i nc 1 ude <st r i ng. h> / 


/ For 


string functions 


#i n c 1 ude <process. h> / 


/ For 


ex i t ( ) , etc. 


#i n c 1 ude <ma 1 1 o c . h > / 


/ For 


ma 1 1 o c ( ) , c a 1 1 o c ( ) , r e a 1 1 o c ( ) , f r e e ( ) 


#i n c 1 ude <s e a r c h . h > / 


/ For 


qsor t ( ) 


#i nc 1 ude <t i me. h> / 


/ To i 


nitialize the random- number functions 



/* B-tree search and add, find, and delete 

* Adapt ed from 

* ALGORI THMS+DATA ST RUCT U RE S =P ROGRA MS by N. Wi r t h 

* 

* Implemented for BDS C by H. Katayose (JUG-CP/M No. 179) 

* Implemented for ANSI C by P. Hipson ( CUG) 

*/ 

/* PAGESI ZE is better at 8 (less memory fragmentation) */ 

#def i ne PAGE SI ZE 2 

tdefine HALFPAGESI ZE ( PAGESI ZE / 2) 

#def i ne PAGE struct _ p a g e 

#d e f i n e ITEM struct item 



#def i ne ROOT 


0 


#def i ne Rl GHT 


1 


#def i ne LEFT 


2 


#def i ne TRUE 


(1) 


#def i ne FALSE 


(0) 


/ * Storage all 


ocat i on 


struct header 




{ 




struct header 


unsi gned 





size; 
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struct header base; /* Declare this external data to */ 

struct _ h e a d e r * _ a I I o c p ; /* be used by ma I I o c ( ) */ 



/ * B- 1 r ee structures */ 

struct item 

{ 

i nt nKeyVal ue; 

PAGE * Ri g ht Ref er enc e; 

i n t n Co u n t ; 

}; 

struct _ pag e 

{ 

i n t n I t e mCou n t ; 

PAGE * Lef t Ref er ence; 

ITEM I tem[ PAGESI ZE] ; 

}; 

/ * Function prototypes */ 

nt Searchf i nt nKeyValue, int * nLevel Count , PAGE *a, ITEM *v 

nt Sear chAndAdd( i nt nKeyValue, PAGE * a , ITEM * v ) ; 

nt I nsert( PAGE * a , int i , I TEM *u, I TEM *v) ; 

nt Copyl tem( I TEM * Des t i na t i o n I t e m, ITEM * S o u r c e I t e m) ; 

nt Newl tem( PAGE * * P a g e ) ; 

nt Tr eePr i nt ( PAGE *p, int I, int nRightLeft, int nPosition); 

nt Del et el t em( i nt nKeyValue, PAGE *a); 

nt Under Fl ow( PAGE *c, PAGE *a, int s) ; 

nt Del ete( PAGE *p, PAGE *a, int k) ; 

void Print He Ip(void); 

/* The ma in program */ 

int ma i n ( ) 

{ 

int i ; 

int i ; 



continues 
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Listing 10.6. continued 

i n t nKeyVal ue; 

i nt h; 

i nt nLevel Count =0; 

char c hOper at i on ; 

char s z Co mma n d [ 132] ; 

PAGE *q; 

PAGE * r o o t ; 

ITEM u; 



printf("\n\nBTREE: Demo program for B-trees\n" 

■ \ n " 



Co mma n 


d 


a r e : \ n " 




A 


# 


- Adds key # ( 


integer 0 - 32767) . \ n" 


D 


# 


- Del et es key 


# (integer 0 - 3 2 7 6 7 ) . \ n " 


S 


# 


- Searches for 


key # (integer 0 - 3 2 7 6 7 ) . \ n " 


R 


# 


- Adds # r a ndo 


m keys (integer 0 - 2000). \n" 


H 




- Prints a h e 1 


p s c r e e n . \ n " 


T 




- Prints the c 


u r r e n t B - 1 r e e st ruct ure. \ n" 


X 




- Exits, after 


a c o nf i r mi n g p r o mpt . \ n \ n " ) ; 



root = NULL; 

whi I e (TRUE) 

{ 

printf("\n\n Co mma n d ? " ) ; 
get s ( s z Comma nd ) ; 

sscanf ( szCommand, " %c %d", StchOperat i on, &n Key Va I u e ) ; 

swi t ch( chOperat ion) 
{ 

case ' h' : 
case ' H' : 

Pr i nt Hel p( ) ; 

break; 
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c cc 



case ' r ' : 
case ' R' : 

printf( "ADDING %d N 0 D E S \ n " , nKeyVal ue); 
srand( ( unsi gned) t i me( NULL) ) ; 

i f ( nKeyVal ue > 2 00 0) 

{ 

nKeyVal ue = 2000; 

} 

for ( i =0; i < nKeyVal ue; i ++) 

{ 

j = r a nd ( ) ; 

if ( Sea r c h A n d Ad d ( j , root, &u) ) 

{ 

q = root; 

Ne wl t e m( &r o o t ) ; 

r o o t - > n I t emCount = 1; 

root - >LeftRefer ence = q; 

Co py I t e m( &r o o t - >l t e m[ 0 ] , &u) ; 

} 

} 

Tr eePr i nt ( r oot , 0, ROOT, 0) ; 
break; 

case ' s ' : 
case ' S' : 

nLevel Count = 0; 

if (( Sear c h ( nKeyVal ue, &nLevel Count , root, &u))) 

{ 

pri ntf( "SEARCH KEY %d found by searching %d \ 
I e v e I s \ n " , 
nKeyVal ue, 
nLevel Count ) ; 

} 

el se 

{ 

continues 
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printf(" SEARCH KEY %d NOT FOUND searching %d \ 
I e v e I s \ n " , 
nKeyVal ue, 
nLevel Count ) ; 

} 



break; 

case ' a ' : 
case ' A' : 

pr i ntf ( "ADD KEY %d\ n", n Key Va I ue) ; 

if ( Sear chAndAdd( nKeyVal ue, root, &u)) 

{ 

q = root; 

Newl t em( &r oot ) ; 

root - >nl te mCo u n t = 1 ; 

root - >LeftReference = q; 

Co py I t em( &r o o t - >l t e m[ 0] , &u) ; 

} 

Tr eePr i nt ( r oot , 0, ROOT, 0) ; 

break; 

case ' t ' : 
case ' T' : 

pr i ntf ( " PRI NT T RE E\ n") ; 

Tr eePr i nt ( r oot , 0, ROOT, 0) ; 

break; 

case ' d' : 
case ' D' : 

pri ntf ( * DELETE KEY %d\ n" , nKeyVal ue) ; 
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if ( Del etel tem( n K e y V a I lie, root)) 
{ 

if (root->nl temCount == 0) 



} 

} 

TreePri nt( root, 0, ROOT, 0) ; 

break; 

case ' x' : 
case ' X' : 

p r i n t f ( " C o n f i r m exit, y | n : " ) ; 

s c a n f ( " %c " , &c hOper at i on) ; 

if ( c hOper at i o n == ' y ' | 
chOperat i on == ' Y' ) 

{ 

exi t ( 0) ; 

} 

break; 
default: 

pr i ntf ( "\ aUnknown operation ' %c ' \ n " , 



q = root; 

root = q- >Lef t Ref er ence; 



c hOper a t i o n ) ; 



break; 



r et ur n( 0) ; 



i nt Search! 
i nt 
i nt 



nKeyVal lie, 
*nLevel Count , 



continues 
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Listing 10.6. continued 

PAGE *a, 
ITEM *v) 



ITEM u; 

/ / p r i n t f ( " S e a r c h ( ) . . . \ n " ) ; 

if (a == NULL) 
{ 

r et ur n( FALSE) ; 

} 

for (i = 0; i < a- >nl temCount && nKeyValue > a - >l tem[ i ] . nKeyVal ue; 
i ++) 

{ 
} 

if (nKeyValue == a - >l tem[ i ] . nKeyVal ue && i < a - >nl temCount) 

{ 

return(TRUE) ; 

} 

else 

{ 

+ + ( * nLevel Count ) ; 

retur n( Search( nKeyVal ue, nLevel Count, 

i ? a - > I t e m[ i - 1] . Ri ght Re f er ence : a - >L ef t Ref e r e n c e , &u)); 

} 

} 



i n t Sea r c h An d Ad d ( 
i nt nKeyVal ue, 
PAGE *a, 
ITEM *v) 
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{ 



ITEM u; 

// pri ntf ( "Sear chAndAddf ) . . . \ n") ; 

if (a == NULL) 

{ 

v - >n Key Va I ue = n Key Va I u e ; 
v - >n Co u n t = 1 ; 
v - >Ri ght Reference = NULL; 
return TRUE; 

} 

for (i = 0; i < a - >nl temCount && nKeyVal ue > a - >l tem[ i ] . nKeyVal ue; 



if ( nKeyVal ue == a - >l tem[ i ] . nKeyVal ue && i < a - >nl temCount) 

{ 

a- >l t em[ i ] . nCount + + ; 

} 



if ( SearchAndAdd( nKeyVal ue, 

i ? a - > I t e m[ i - 1] . Ri ght Ref er ence : a - >L ef t Ref e r en c e , &u)) 

{ 

return ( I ns er t ( a , i , &u, v ) ) ; 

} 



i + + ) 



else 



return 



FALSE; 



i n t Insert! 
PAGE 



*a, 



continues 
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Listing 10.6. continued 



i nt i , 
ITEM *u, 
ITEM *v) 



{ 



PAGE *b; 

i nt j ; 

i nt h; 

/ / p r i n t f ( " I n s e r t ( ) . . . \ n " ) ; 

if ( a - >n I temCount < P AGE _ S I ZE) 

{ 

for (j = a->nltemCount; j > = i +1; j-) 

{ 

Copyl t em( &a- >l t em[ j ] , & a - > I t e m[ j - 1]); 

} 

++a- >nl t emCount ; 

Co py I t e m( &a - >l t e m[ i ] , u ) ; 

r et ur n( FALSE) ; 

} 

else 

{/* Page a is full. Split it and assign the emerging item to v. */ 
Newl t em( &b) ; 

if ( i <= HALFPAGESI ZE) 

{ 

if ( i == HALFPAGESI ZE) 

{ 

Copyl tem( v, u ) ; 

} 

else 

{ 

Copyl t e m( v , &a - >l t e m[ HALFPAGESI ZE ■ 1]); 



404 



Data Management: Sorts, Lists, and Indexes 



for ( j = HALFPAGESI ZE - 1; j >= i +1; j - - ) 

{ 

Copyl t em( &a- >l t em[ j ] , & a - > I t e m[ j - 1]); 

} 

Copyl tem( &a - >l t em[ i ] , u ) ; 

} 

for (j =0; j <= HALF_PAGE_SI ZE - 1; j + + ) 

{ 

Copyl tem( &b - >l t em[j ] , &a - >l t e m[ j + HALFPAGESIZE]); 

} 

} 

else 

{ 

i - = HAL F_ P A G E _ S I ZE; 

Copyl tern) v, &a - >l tem[ HALF PAGE SI ZE] ) ; 

for ( j =0; j <= i ■ 2; j + + ) 

{ 

Copyl tem( &b - >l t em[j ] , & a - > I t e m[ j + HAL F_ PAGES I ZE + 1]); 

} 

Copyl t em( &b- >l t em[ i - 1] , u); 

for (j = i ; j <= HALF PAGE SI ZE - 1; j + + ) 

{ 

Copyl tem( &b - >l t em[j ] , & a - > I t e m[ j + HALFPAGESIZE]); 

} 



i f ( HAL F _ P AGE_ S I ZE ==0) 

{ 

a - >nl temCount = 1 ; 
b- >nl temCount = 1 ; 

} 

else 

{ 

a - > n I temCount = HAL F _ P A G E _ S I ZE; 
b- >nl temCount = HALF PAGE SI ZE; 
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b- >L e f t Ref er ence = v - >Ri ght Reference; 
v - > R i g h t Reference = b; 

} 

return(TRUE) ; 



} 



i nt Copy I t em( 

ITEM * Des t i na t i on I t em, 
ITEM * So u r c e I t e m) 

{ 

// pr i ntf ( "Copyl t em( ) . . . \ n") ; 

Desti nati onl tern- >nKeyVal ue = Sourcel tern- >nKeyVal ue; 

Desti nati onl tem- >Ri ghtReference = Sourcel tern- >Ri ghtReference; 
Desti nati onl tern- >nCount = So u r c e I t e m- >n C o u n t ; 



r et u r n ( 0 ) ; 



} 



i nt Newl t em( 

PAGE * * P a g e ) 

{ 

// pr i ntf ( " Newl t e m( ) . . . \ n " ) ; 

if ( ( * Pa g e = (PAGE * ) ma I I o c ( s i z e of ( * * Pa g e ) ) ) == NULL) 

{ 

fpri ntf(stderr, "Couldn't allocate me mo r y I \ n " ) ; 
exi t ( 16) ; 

} 

/* ma I I o c ( ) doesn't initialize storage, so we do. */ 
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III] 

c cc 



memset(*Page, 0, si zeof ( **Page) ) ; 
r e t u r n ( 0 ) ; 

} 



i nt Tr eePr i nt ( 

PAGE * Pa g e , 
i n t n Le v e I , 
i nt nRi ghtLeft, 
i nt n P o s i t i on) 

{ 

i nt i ; 

i nt j ; 

i f ( Page ! = NULL) 
{ 

for (i = 0; i < Page- >nl t emCount ; i ++) 

{ 

s wi t c h ( n Ri g ht Let t ) 

{ 

case ROOT: /* Should have only one root */ 
p r i n t f ( " \ n " ) ; 

pr i ntf ( " ( ROOT %2d) ", nLevel ) ; 
break; 



case LEFT: / 
p r i n t f ( " 
break; 



Happens al I 
L %2d %2d) 



l e t i me 
nLevel 



n Pos i t i on ) 



case RI GHT: / * Happens all t he t i me */ 

pr i ntf ( " ( R %2d %2d) " , nLevel , nPosi t i on) ; 
break; 



default: /* Should never happen */ 
pr i ntf (" ERROR "); 
break; 



continues 
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for ( j =0; j < n L e v e I ; j + + ) 

{/* Adjust the starting column for the variable */ 
p r i n t f ( " " ) ; 

} 



p r i n t f ( " %5 d \n", Page - >l tem[ i ] . nKeyVal ue) ; 



if ( Page- >l t em[ i ] . Ri g ht Ref er enc e != NULL) 

{ 

TreePri nt( Page - >l tem[ i ] . Ri ght Refer ence, 
n L e v e I +1, RI GHT, i + 1) ; 

} 

} 

if ( Page- > L e f t Ref er enc e ! = NULL) 

{ 

TreePri nt( Page - >LeftReference, nLevel + 1, LEFT, 0); 

} 

} 

r et u r n ( 0 ) ; 

} 



i nt Del et el t em( 

i nt nKeyVal ue, 
PAGE *a) 



i nt i ; 

i nt k; 

i nt I ; 

i nt r ; 

PAGE *q; 
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// 



pr i nt f ( "Del etel t em( ) . . . \ n" ) ; 



if (a == NULL) 



pri ntf( "Key is not in tree! Cannot delete this key. \ n " ) ; 
return FALSE; 

} 

else 

{/ * Binary array search */ 

for (I =0, r = a- >n I t emCou nt ■ 1 ; I <= r ; ) 
{ 

k = (I + r) / 2; 

if (nKeyValue <= a - >l t e m[ k ] . n Key Va I u e ) 

{ 

r = k - 1; 

} 

if (nKeyValue >= a - >l t e m[ k ] . n Key Va I u e ) 

{ 

I = k + 1; 



q = (r == -1) ? a->LeftReference : a - >l tem[ r] . Ri ght Reference; 
if (I ■ r > 1) 

{/* Found; now delete I t e m[ k ] */ 
if ( q == NULL) 

{/* a is a terminal page */ 
- (a->nltemCount); 

for ( i = k ; i < a - >n I t e mCo u n t ; i ++) 

{ 

Copyl t em( &a- >l t em[ i ] , & a - > I t e m[ i + 1] ) ; 

} 

return ( a - >n I t e mCo u n t < HALFPAGESI ZE) ; 

} 

else 

{ 

if ( Del ete( q, a, k) ) 

{ 



continues 
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r et u r n ( Unde r F I o w( a , q , r ) ) ; 

} 

} 

} 

else 

{ 

if ( Del etel t em( nKeyVal ue, q ) ) 

{ 

return Under Fl ow( a, q, r); 

} 

} 

} 

} 



i nt Under F I o w( 
PAGE *c, 
PAGE *a, 
i nt s) 



PAGE *b; 



nt 


i ; 


nt 


k; 


nt 


mb ; 


nt 


mc ; 



// pr i nt f (" Under Fl ow( ) ... \ n" ) ; 
mc = c - >n I t e mCo u nt ; 

if ( s < mc - 1 ) 

{ 

++s; 

b = c - >l tem[ s] . Ri ght Reference; 
mb = b- >n I t e mCo u n t ; 



410 



Data Management: Sorts, Lists, and Indexes 



C C C 
III] 

c cc 



k = ( mb ■ HAL F_ P A G E _ SI ZE +1) / 2; 

Copyl tern) &a - >l tem[ HALF_ PAGE_ SI ZE - 1], &c - > I t e m[ s ] ) ; 

a- >l t em[ HALFPAGESI ZE - 1] . Ri ghtReference = b- >L e f t Ref er ence; 

if ( k > 0) 
{ 

f or ( i =0; i < k ■ 1 ; i + + ) 

{ 

Copyl tem( &a - >l t em[ i + HALFPAGESIZE], & b - > I t e m[ i ] ) ; 

} 

Copy I t em( &c - >l t em[ s ] , & b - > I t e m[ k - 1]); 
c - >l tem[ s] . Ri ght Reference = b ; 

b- >L ef t Ref e r e n c e = b - >l t e m[ k - 1] . Ri ght Ref er ence; 
mb - = k; 

for ( i =0; i < mb; i ++) 

{ 

Copy I t em( &b- >l t em[ i ] , & b - > I t e m[ i + k]); 

} 

b- >nl temCount = mb ; 

a - > n I temCount = HAL F_ PAGE_ S I ZE - 1 + k; 
r et ur n( FALSE) ; 

} 

else 

{ 

for ( i =0; i < HAL F_ P A G E _ SI ZE; i + + ) 

{ 

Copy I t em( &a- >l t em[ i + HALFPAGESIZE], & b - > I t e m[ i ] ) ; 

} 

for ( i = s ; i < mc ; i ++) 
{ 

Copyl tem( &c - >l t em[ i ] , &c - >l t e m[ i + 1]); 

} 

continues 
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a- >nl temCount = P A G E _ S I ZE; 
c - >nl temCount = mc - 1 ; 

} 

} 

else 

{ 

b = (s == 0) ? c - > L e f t Ref e r e nc e : c - >l t e m[ s - 1 ] . Ri g h t Ref e r en c e ; 

mb = b - >nl temCount + 1 ; 

k = ( mb ■ HALF PAGE SI ZE) / 2; 

if ( k > 0) 

{ 

f o r ( i = HALFPAGESI ZE - 2; i >= 0; i ■■) 

{ 

Copy I t em( &a- >l t em[ i + k] , &a- >l t em[ i ] ) ; 

} 

Copyl tem(&a - >l tem[ k - 1], &c ■ >l t em[ s ] ) ; 

a - > I t e m[ k - 1] . Ri ghtReference = a- > L e f t Ref er ence; 

mb ■ = k ; 

for ( i = k - 2; i >= 0; i ■ - ) 

{ 

Copyl tem( &a - >l tem[ i ] , & b - >l t e m[ i + mb] ) ; 

} 

a - >L ef t Ref e r e n c e = b - >l tem[ mb] . Ri ghtRef erence; 

Copyl tem(&c - >l tem[s] , &b->ltem[mb - 1]); 

c - >l tem[ s] . Ri ght Reference = a ; 

b - > n I t emCount = mb - 1; 

a- >nl temCount = HALF PAGE SI ZE - 1 + k; 

return! FALSE) ; 

} 

else 
{ 

Copyl t em( &b- >l t e m[ mb] , &c- >l tern] s ] ) ; 
b->ltem[mb]. Right Reference = a->LeftReference; 
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for ( i =0; i < HALFPAGESI ZE - 1; i + + ) 

{ 

Co py I t e m( &b - >l t e m[ i + mb] , &a- >l t em[ i ] ) ; 

} 

b- >nl temCount = P AG E _ S I ZE; 
c - >nl temCount = mc ■ 1 ; 

} 

} 

return! TRUE) ; 

} 



i nt Del e t e ( 

PAGE *p, 
PAGE *a, 
i nt k) 

{ 

PAGE *q; 

// pri ntf ("Del ete() . . . \ n"); 

if ((q = p - >l tem[ p - >nl temCount - 1] . Ri ghtReference) ! = NULL) 

{ 

if (Del ete(q, a, k) ) 
{ 

r et u r n ( U n d e r F I o w( p , q, p- >nl temCount - 1)); 

} 

} 

else 

{ 

p - >l tem[ p - >nl temCount ■ 1 ] . Ri g h t Ref e r e n c e = a 

- >l tem[ k] . Ri ght Reference; 

Copyl tem( &a - >l tem[ k] , &p - >l tem[ p - >nl temCount ■ 1]); 

- ( p - >nl t emCount ) ; 

return! p- >nl temCount < HALF PAGE SI ZE) ; 

} 

} 
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void P r i n t H e I p ( ) 
{ 



p r i n t f ( 

' \ n\ nBTREE: Demo program for B-trees\n" 

\ n" 

' Comma n d a r e : \ n " 

A # - Adds key # (integer 0 - 3 2 7 6 7) . \ n " 

D # - Del et es key # (integer 0 - 3 2 7 6 7) . \ n" 

S # - Searches for key # (integer 0 - 3 2 7 6 7). \n" 

R # - Adds # random keys (integer 0 - 2 0 0 0 ) . \ n " 

H - Prints a help screen. \n" 

T - Prints the current B-tree structure. \n" 

X - Exits, after a confirming prompt.\n\n"); 



p r i n t f ( " \ n " 

"All keys (the items that are placed in the tree) are \ 
i ntegers,\n" 

"ranging fromO to 32767. Each item is added to the tree when \ 
t h e \ n " 

"Add command is i ssued. \ n" ) ; 
p r i n t f ( " \ n " 

"A new key is added with the Add command. Enter an A and a n \ n " 
"integer v a I u e . \ n " ) ; 

p r i n t f ( " \ n " 

"An existing key can be deleted by using the Delete co mma n d . \ n " 
"Enter a D followed by an integer key value. If the value \ 
e n t e r e d \ n " 

"is not a valid key, the program will tell you s o . \ n " ) ; 
p r i n t f ( " \ n " 

"When you search for a key, the tree is traversed. If the key\n" 
"is found, the level where it was found is provided. If the \ 
k e y \ n " 

"is not found, a me s s a g e is p r i n t e d . \ n " ) ; 
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p r i n t f ( " \ n " 

"The Repeat command is used to build a table of random keys. \ 
T h e \ n " 

" r a n d ( ) function is called the specified number of times. No\n" 
"test for duplicates is made, but duplicates for random- numb er\n" 
"counts of less than several hundred are infrequent. \ n " ) ; 

p r i n t f ( " \ n " 

"To print the entire tree structure, use the Tree co mma n d . \ 
T h i s \ n " 

" c o mma nd is entered as a T. There are no parameters for " 
"this co mma n d . \ n " ) ; 

printf("\n" 

"To end the program, use the Exit command. Enter an X, with no\n" 

"parameters. You will be pro mp ted to confirm that you want to\n" 
" e x i t . \ n " ) ; 

p r i n t f ( " \ n " 

"If you don't enter the key (or count for Repeat), the \ 

previ ous\ n" 
"value for the count is u s e d . \ n " ) ; 



TheBTREE program arranges its tree in a way that you might not expect. The 
memory allocation functions could be called for each node, but this would be 
inefficient. Rather, each allocated block has from two to eight nodes. (You could have 
morethan eight, buttheB-tree'sperformancemightsuffer.) I chosea block that would 
contain two data items (or nodes). 

/* PAGESI ZE is better at 8 (less memory fragmentation).*/ 

#def i ne P AG E _ S I ZE 2 

#define HAL F _ PAGE_ SIZE ( PAGESI ZE / 2) 

Three structures are created for the B -tree. First, a structure is created for the 
ma 1 1 o c ( i function: 

/ * Storage allocation structures used by ma I I o c ( ) * / 
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struct header 
{ 

struct header *_ptr; 
unsi gned si z e ; 

}; 

struct header _base; /* Declare this external data to */ 

struct header * _ a I I o c p ; /* be used by ma I I o c ( ) */ 

T henext structure, called i t e m, containsi nformation specific to each data item 
(node) in the B-tree. T his is the structure that would contain your item-specific data, 
such as the node's key (this is an integer in the example program, but it could be a 
character stri n g as wel I ) , a poi nter to a structurecontai n i n g the i tem 's data, or an index 
into a file that would have the item's data. 

struct _ i t e m 

{ 

i nt n Key Va I u e; 

PAGE * Ri ght Ref er ence; 

i nt nCount ; 

}; 

The third structure, _ page , forms the building block for the B-tree. This 
structurecontainsa count of items (from 1 to page si z e ), theblock'sleft branch, and 
an array ofpAGESi ze i terns. Them temcount variableindicateshowmanyoftheitems 
are used. 

struct page 
{ 

i nt n I t e mCo u nt ; 
PAGE * Lef t Ref er ence; 
ITEM I t em[ PAGESI ZE] ; 

}; 

T hemajority of BT R E E .C 'smain function processes keyboard input. T hiscode 
issimilarto thecodein other exam pie programs, so thissectiondescribesonlythethree 
most important blocks. T hefirst block isexecuted when theuser searchesfor a record. 
Thesear ch( i function iscalled, and ispassed parametersthatincludethekeytheuser 
is searching for and the root nodefor the B-tree. 

case ' s' : 
case ' S' : 

nLevel Count = 0; 
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if (( Search! nKeyVal ue, &nLevel Count , root, &u))) 

{ 

pri ntf ("SEARCH KEY %d found by searching %d I e v e I s \ n " , 
n Key Va I ue , 
nLevel Count) ; 

} 

else 

{ 

pri ntf ("SEARCH KEY %d NOT FOUND searching %d I eve! s \ n " , 
n Key Va I ue , 
nLevel Count) ; 

} 

break; 

T hesea r c h An dAd d ( ) function searchesfor theitem. If theitem cannot befound, 
sear c hAndAdd ( ) addstheuser'skeytotheB-tree.Thisfunction returnsTRUE if theitem 
wasnot added becausetheB-treedoesnot exist yet. If the B -tree does not exist yet, the 
B-tree is created and the item is added as the root of the node. 

case ' a' : 
case ' A' : 

pr i ntf ( " ADD KEY %d\ n" , n Key Va I ue) ; 

if ( Sear c hAndAdd ( nKeyVal ue, root, &u)l 

{ 

g = root; 

Newl t em( &r oo t ) ; 

r o o t - >n I t e mCo u n t = 1 ; 

r oot - >Lef t Ref er ence = g; 

Co py I t e m( &r o o t - >l t e m[ 0 ] , &u ) ; 

} 

Tr eePr i nt ( r oot , 0, ROOT, 0) ; 
break; 

The Dei etei t em( ) function is called when the user wants to delete a key. If the 
item being deleted isthecurrent root, Dei etei tem( ) returnsTRUE , signalingthatanew 
root must be created from another node. 



case ' d' 
case ' D' 
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pr i ntf ( " DELETE KEY %d\ n" , n Key Va I ue) ; 

if ( Del etel tem( nKeyVal ue, root)) 

{ 

if ( root - >nl temCount == 0) 

{ 

q = root; 

root = q - >L ef t Ref e r e n c e ; 

} 

} 

Tr eePr i nt ( r oot , 0, ROOT, 0) ; 
break; 

Let'slookatsomeofthefunctionsthatdotheworkintheBTREE program. The 
searcht) function simplyfollowsthetree, startingatthegiven node, until thespecified 
key isfound or it isknown that thekey is not in theB-tree. Thesear cm ) function 
works recursivdy: it calls itself each timeitsearchesanodeand doesnot find amatch 
for the specified key. By calling itsdf, sear cm ) can useasimplefunction to perform 
a search to any level: 

i n t Search! 

i nt nKeyVal ue, 

int *nLevel Count , 

PAGE *a, 

ITEM *v) 



int i ; 

ITEM u; 

// pr i ntf ( "Search! )... \ n") ; 

if (a == NULL) 
{ 

r et ur n( FALSE) ; 

} 

for (i = 0; i < a- >nl temCount && nKeyVal ue > a- >l t em[ i ]. nKeyVal ue; 
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i ++) 

{ 

} 

if ( nKeyVal ue == a- >l t em[ i ] . nKeyVal ue && i < a - >nl temCount) 

{ 

return(TRUE) ; 

} 

Search uses a simple integer comparison to check for a match. If thekey had been 
a character string, you could use a call to s t r c mp ( ) or some other character comparison 
function. 

The recursive call tosearcho follows. The recursion isperformed by using a 
comparison of the variable i and by passing the current node's right or left node to 
search. 

else 

{ 

+ + ( * n Le v e I Co u n t ) ; 

return( Searchf nKeyVal ue, nLevel Count, 

i ? a - > I t e m[ i - 1] . Ri ght Ref er ence : a- > L e f t Ref er ence, &u)); 

} 

} 

The sear c h An d Ad d ( ) function is similar to the sea r c h ( ) function. When 
search! ) ends, however, it simply returnsaflag showing that thekey wasnot found. 
When sear chAndAddi ) returns, it adds the key to the current B-tree. 

int Sear c hAndAdd ( 
i nt nKeyVal ue, 
PAGE *a, 
ITEM *v) 



int i ; 

ITEM u; 

// pri ntf ( "Sear chAndAddi ) . . . \ n") ; 
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If thefunction was passed a null pointer, the program is preparing to add this 
key to a node. Then sear chAndAddi i prepares to add the key as the node, and returns 
true to tell the caller that a node has been created. 

The root node is created in themain program becausetherootnodeis"owned" 
by the main program, not by the B-tree functions: 

if (a == NULL) 

{ 

v - >nKeyVal ue = nKeyVal ue; 
v - >n Co u n t = 1 ; 
v - >Ri ght Reference = NULL; 
return TRUE; 

} 

The following code, which issimilar to thecodein sear c h ( ) , isused to find a 
match: 

for (i = 0; i < a - >nl temCount && nKeyVal ue > a- >l t em[ i ] . nKeyVal ue; 
i + + ) 

{ 
} 

if ( nKeyVal ue == a - >l tem[ i ] . nKeyVal ue && i < a - >nl temCount) 
{ 

I n thefollowing code, if amatch isfound, a counter of matches is incremented. 
Thisallows our version of B-treetohaveduplicatekeys, with onlyonecopyofthekey 
kept in memory. 

a->l tem[ i ] . nCount++; 

} 

else 

{ 

if ( Sea r c h An d Ad d ( n Ke y Va I u e , 

i ? a - > I t e m[ i - 1 ] . Ri g h t Ref e r e n c e : a - >Lef t Ref e r e nc e , &u)) 

{ 

Ifthesear chAndAddi i function doesnotfind thekey, thei nsert ( ) function adds 
the key to the B-tree (in the correct place), as follows: 

return ( I ns e r t ( a , i , &u , v) ) ; 

} 

} 
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return FALSE; 

} 

The i nserto function adds the current key value to the passed node by 
computing the number of items in the current block. If the block is too full, the 
function splits it into two blocks: 

i nt Insert! 

PAGE *a, 

i nt i , 

ITEM *u, 

ITEM *v) 



/ / p r i n t f ( " I n s e r t ( ) . . . \ n " ) ; 

if ( a - > n I temCount < PAGESI ZE) 

{ 

for (j = a->nltemCount; j >= i +1; j - ) 
{ 

Copy I t em( &a- >l t em[ j ] , & a - > I t e m[ j - 1]); 

} 

++a - >n I t e mCo u n t ; 

Copyl tem( &a- >l t em[ i ] , u) ; 

return! FALSE) ; 

} 

else 

{/* Page a is full. Split it and assign the emerging item to v. */ 
Newl t em( &b) ; 

if ( i <= HAL F_ P A G E _ S I ZE) 

{ 

if ( i == HAL F_ PAGES I ZE) 

{ 



PAGE 



* b; 



i nt 



J ; 



i nt 
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Copyl tem( v, u ) ; 

} 

else 
{ 

Copyl t e m( v , &a - >l t e m[ HALFPAGESI ZE ■ 1]); 

for (j = HALFPAGESI ZE - 1; j >= i +1; j - - ) 

{ 

Co py I t em( &a - >l t e m[ j ] , &a - >l t e m[ j - 1]); 

} 

Copyl tem( &a - >l t em[ i ] , u) ; 

} 

for (j =0; j <= HAL F_ PAGE_ S I ZE - 1; j + + ) 

{ 

Copy I t em( &b- >l t em[ j ] , &a - >l t e m[ j + HAL FPAGESI ZE] ) ; 

} 

} 

else 

{ 

i - = HALF PAGE SI ZE; 

Copyl t e m( v , &a - >l t e m[ HALFPAGESI ZE] ) ; 

for ( j =0; j <= i ■ 2; j + + ) 

{ 

Copy I t em( &b- >l t em[ j ] , &a - >l t e m[ j + HAL F_ PAGE_ SIZE + 1]); 

} 

Copy I t em( &b- >l t em[ i - 1 ] , u) ; 

for (j = i ; j <= HAL F_ PAGE_ S I ZE - 1; j + + ) 

{ 

Copy I t em( &b- >l t em[ j ] , &a - >l t e m[ j + HAL FPAGESI ZE] ) ; 

} 



i f ( HALF_PAGE_SI ZE == 0) 

{ 

a - > n I t e mCo u n t = 1 ; 
b - > n I t emCount = 1; 
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else 



a- >nl t emCount = HAL F _ P A G E _ S I ZE; 
b- >nl temCount = HAL F _ PAG E_ S I ZE; 



b- >L ef t Ref er e n c e = v - >Ri ght Reference; 
v - >Ri ght Reference = b; 

} 

return! TRUE) ; 

} 

The copy i tem( ) function copies information from the source item to the 
destination item. I n thedaysof non-AN SI C , structurescould not beassigned to each 
other. AN SI C supports structure assignments, however, so you could replace 
copy 1 1 em( ) with assignment statements. 

i nt Copyl t em( 

ITEM * Des t i na t i o n I t e m, 
ITEM * So u r c el t e m) 



r e t u r n ( 0 ) ; 

} 

TheNewi temi i function is used to create a new node. Newi t em( ) usesmaiioco 
to allocate memory for the new node, then clears the memory. 

i nt Newl t em( 

PAGE **Page) 



// 



pr i ntf ( "Copyl t em( ) ... \ n" ) ; 



Dest i nat i onl t em- > n K e y V a I ue 
Desti nati onl tem- >Ri ght Refer ence 
Dest i nati onl tern- > n C o u n t 



So u r c e I tem- >n Key Va I u e ; 

S o u r c e I tem- >Ri g h t Ref e r en c e ; 

Sour eel tem- >nCount ; 
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// pr i ntf ( " Newl t e m( ) . . . \ n " ) ; 

if ( ( * Pa g e = (PAGE * ) ma I I o c ( s i z e of ( * * Pa g e ) ) ) == NULL) 

{ 

fpri ntf(stderr, "Couldn't allocate me mo r y ! \ n " ) ; 
exi t ( 16) ; 

} 

/* ma I I o c ( ) doesn't initialize storage, so we do... */ 
memset(*Page, 0, sizeof(**Page)); 
r et u r n ( 0 ) ; 

} 

TheTreePr i nt ( i function printstheB-tree. T hisfunction knows which level it 
is being called for and prints this information with the current node's values 

int TreePri ntf 

PAGE * P a g e , 
int n Level , 
int n R i ght Left , 
int nPosition) 



int i ; 
int j ; 

IfTreePri nt( ) iscalled with aNUL l node, itdoesnothing.Otherwise,TreePr i nt( ) 
prints the level, prints whether it istheleft or right nodeof its parent, and indents the 
node's numeric value (its key value) by four spaces for each level. 

if (Page ! = NULL) 

{ 

for (i = 0; i < Page->nl temCount; i+ + ) 

{ 

s wi t c h( n R i ght Lef t ) 

{ 

case ROOT: /* Should have only one root */ 
p r i n t f ( " \ n " ) ; 

pri ntf ( "( ROOT %2d) ", n Level ) ; 
break; 
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case LEFT: /* Happens all the time */ 

printf("(L %2d %2d) ", n Level, nPosition) 
break; 



case Rl GHT: / * Happens all the t i me */ 

p r i n t f ( " ( R %2 d %2 d ) " , nLevel , nPosition); 
break; 



default: /* Should never happen */ 
pri n t f ( "ERROR "); 
break; 

} 

for ( j =0; j < nLevel ; j ++) 

{/* Adjust the starting column for the variable */ 
pri n t f ( " " ) ; 

} 

After the necessary header information is displayed, the key value is printed. 
Remember, the key does not need to bean integer. If it was a character string, you 
would probably have to change thefollowing line: 

pri n t f ( " %5 d \n", Page - >l tem[ i ] . nKeyVal ue) ; 

After printing thekey value, TreePr i nt( ) , likes ear cm ) , calls itself recursively, 
and is passed information on whether theright nodeortheleft nodeisbeingfollowed: 

if ( Page- >l t em[ i ] . Ri g ht Ref er enc e != NULL) 

{ 

TreePri nt( Page - >l tem[ i ] . Ri ghtReference, 
nLevel +1, RI GHT, i + 1) ; 

} 

} 

if ( Page- >Lef t Ref er ence ! = NULL ) 

{ 

TreePri nt( Page - >LeftReference, nLevel + 1, LEFT, 0); 

} 

} 

r et u r n ( 0 ) ; 

} 



425 



Part 1 1 • Managing Data in C 



TheDei etei tem( ) function deletes a node. Dei etei tem( i first checksthat a node 
and an item to be deleted have been passed. 

i nt Del etei tem( 

i nt nKeyVal lie, 
PAGE *a) 

{ 



i nt 


i 


i nt 


k 


i nt 


1 


i nt 


r 


PAGE 


* 



// pr i ntf ( "Del etei tem( ) ... \ n") ; 

if (a == NULL) 

{ 

pri ntf( "Key is not in tree! Cannot delete this k e y . \ n " ) ; 
r et ur n( FALSE) ; 

} 

else 

Remember binary searches from earlier in the chapter? The following binary 
search uses the same technique: halving the list you are searching, depending on the 
result of the comparison of a given node and the user's key: 

{/ * Binary array search */ 

for (I =0, r = a - > n I t emCo u nt ■ 1; I <= r ; ) 

{ 

k = (I + r) / 2; 

if (nKeyValue <= a - >l tem[ k] . nKeyVal ue) 
{ 

r = k - 1; 

} 

if (nKeyValue >= a- >l t em[ k] . nKeyVal ue) 

{ 

I = k + 1; 

} 

} 
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q = (r == -1) ? a->LeftReference : a - >t tem[ r] . Ri ght Reference; 
if (I - r > 1) 

{/* Found; now delete I t e m[ k ] */ 
if ( q == NULL) 

{ / * a is a t er mi nal page */ 
■ ■ ( a - >nl t emCount ) ; 

for ( i = k; i < a - >n I t e mCo u n t ; i ++) 

{ 

Copyl tem(&a - >l tem[ i ], & a - > I t e m[ i + 1]); 

} 

return ( a - >n I t e mCo u n t < HALFPAGESI ZE) ; 

} 

else 

{ 

if ( Del ete( q, a, k) ) 

{ 

r et ur n( Under Fl ow( a, q, r ) ) ; 

} 

} 

} 

else 
{ 

if ( Del etel tem( nKeyVal ue, q ) ) 
{ 

r et u r n ( Under Fl o w( a, q , r ) ) ; 

} 

} 

} 

} 

The under fi ow( ) function readjusts the B -tree. It shifts the remaining nodes, 
attempting to keep the B -tree as balanced as possible: 

i nt Under Fl ow( 
PAGE *c, 
PAGE *a, 
i nt s ) 

{. . . } 
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Dei etei t em( ) callstheDei ete( ) function to dddethenode. T hisfunction takes 
care of some of the housekeepi ng because there can be more than one key per block. 

i nt Del e t e ( 

PAGE *p, 

PAGE *a, 

i nt k) 

{. . . } 

T he rest of this section describes ways to make some of the routines in BT R E E 
more generic (or more specific, depending on how you look at things). 

First, thekey ischanged to a character field (16 characters long). T hen a new field 
called i Fi i ei ndex isadded to each node; thisfidd isan index to a file's record. To use 
thisnewfidd,sear ch( i should rdurn it asoneof itsparamders.Thei Fi i ei ndex field 
should beset when calling sear chAndAddi ) . 

The rest of this section describes the changes you must make to the B-tree 
functions. Change all rderencestothefunctionsforthenKeyvai ue variableto reflect 
both the new variable's type and the change in its name. 

UseanewparamdertochangethesearchAndAddi ) function and thesea r c h ( ) 
function so that they pass back the i Fi i ei ndex variable. 

ChangeTreePn nt( i so that it printsthei Fi i ei ndex variableinthedebugmode. 

Change the main function so that it can handle a character-based key. 

M ake the following changes to the program's source code. The 1 1 em structure 
should have thefollowing variables: 

struct _ i t e m 

{ 

char szKeyVal ue[ 16] ; 
long I F i I el ndex; 
PAGE * Ri ght Ref er ence; 
i nt n Co u nt ; 

}; 

Change all references to n Key vai ue to reflect thenew data type of szKeyvai ue. 
This means changing references such as the following: 

for (i = 0; i < a - >nl temCount && nKeyValue > a - >l t e m[ i ] . n Key Va I u e ; i + + ) 

to 
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for ( i = 0 ; i < a - >nl temCount && 

s t r c mp ( s z Key Va I u e , a - >l tem[ i ] . szKeyVal ue) > 0; i + + ) 

and changing the reference 

if ( nKeyVal ue == a - >l tem[ i ] . nKeyVal ue && i < a->nltemCount) 

to 

if ( s t r c mp( s z Key Va I u e, a- >l t em[ i ] . sz KeyVal ue) == 0 && 
i < a - > n I t emCou nt ) 

Both of these references are in thesear cm ) function. 

In thesear c h An d Ad d ( ) function, change 

v - >n Key Va I u e = n Key Va I u e ; 

to 

st r c p y ( v - >sz KeyVal ue, nKeyVal ue) ; 

and change 

for (i = 0; i < a - >nl temCount && nKeyVal ue > a - >l tem[ i ] . nKeyVal ue; i + + ) 

tO (asin Search! ) ) 

for ( i = 0 ; i < a - >nl temCount && 

s t r c mp ( s z Key Va I u e , a - >l t em[ i ] . s z Key Va I u e ) > 0; i + + ) 

and the reference 

if ( nKeyVal ue == a - >l tem[ i ] . nKeyVal ue && i < a->nltemCount) 

to 

if ( s t r c mp( s z Key Va I u e, a- >l t em[ i ]. sz KeyVal ue) == 0 && 
i < a - > n I t emCou nt ) 

In copyi tem( ) , change 

Desti nati onl tern- >nKeyVal ue = So u r c el t e m- >n Key Va I u e ; 

to the following (with an added lineforthenew i Fi i ePoi nter structure member): 

strcpyl Desti nati onl tern- >s z Ke y Va I ue, Sourcel tern- >szKeyVal ue) ; 
Desti nati onl tem- >l Fi I ePoi nter = Sourcel tem->l Fi lePoi nter; 

In the Dei etei tem( i function, change 

if ( nKeyVal ue <= a - >l tem[ k] . nKeyVal ue) 
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if ( s t r c mp( s z Key Va I u e, a - >l t e m[ k] . s z Key Va I u e ) <= 0) 

and change 

if ( nKeyVal ue >= a- >l t em[ k] . nKeyVal lie) 



if ( s t r c mp( s z Key Va I u e, a - >l t e m[ k] . s z Key Va I u e ) >= 0) 

These changes are simple to make. Should the key be some other data type, 
similar changes would have to be made. 



Summary 

In this chapter, you learned about data management. 

• Data often must be sorted. You can perform a sort externally by using files and 
calling D OS's sort program or by calling another commercial sort routine. 

• If data can besorted in memory, you can usetheC qsorti i function. 

• There is no provision for merging sorted data files under DOS, but this 
chapter presented a merge utility you can use. 

• M ost operating systems do not have a command for purging a data file of 
duplicates. T his chapter presented a purge utility for this purpose. 

• Linked lists organize data so that it may be retrieved in a specified order 
(usually sorted). Each member in a linked list has a pointer to the next mem- 
ber in the list. Usually, this pointer is the only way to find the members of a 
linked list. 

• Linked lists can be used to group data based on a specific attribute. 

• In a double linked list, the current data object is linked both with its successor 
and its predecessor. 

• Indexed files enable a programmer to sort a much smaller set of data, which is 
then used to access specific data objects. Each record in the index file needs to 
contain only the key value and a pointer to its corresponding data object. 
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• A single data file may havemorethan one index file, each oneindexinga 
different data file field. 

• A B-tree organizes data so that specific data items are accessed easily. 

• B-tree programs work with in-memory and file-based data structures. For 
acceptable performance, however, the tree must be in memory. 



c 

Part III 

c 



Working with Others 



and Other Languages 



M any discussions in previous chapters did not pertain to a particular compiler. In this 
chapter, almost everything isdependent on thetypeof compiler. As in other chapters, 
I assumethatyou areusing a M icrosoft compiler. H owever, I havenoted when some 
thing applies to a Borland or a Watcom compiler. 

Nothing in theANSI standard restrictsC programsfrom containing functions 
written in another language. If your compiler is not covered, do not assumethatyou 
cannot mix languages. M ost compilersincludeat least a provision for writingfunctions 
in assembly. 

You may be asking why anyone would mix languages when C can do almost 
anything. H ere are some good reasons: 

You have a library of application-specific functions written in another 
computer language, such as Pascal or FO RTRAN . For mathematical 
applications, FORTRAN still has many advantages. 

You must create a function that is faster than what an optimizing compiler 
can produce. With assembly, you can directly control the computer's CPU 
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and get every ounce of performance out of it. (Remember, though, that it is 
easy to create assembly functions that are not as efficient as a function 
written in C and compiled with the compiler's optimization turned on.) 

Your project is on a tight schedule, so you must purchase a library of 
functions to save development time. 

When you purchasealibraryoffunctions, besureitincludesthesourcecode. You 
cannot depend on the supplier of the code to respond to your needs, and without 
source code you are on your own. I have never used code written by someone else 
without making at least one change. As well, if the supplier goes out of business, you 
can keep your product running if you have source code. 



Peter's rule: When you buy a library of functions, get the source code. If it is 
unavailable, look for a different product. 



Other Languages 

Thischapter considers four languages other than C: assembly, BASIC, FORTRAN , 
and Pascal .All havebeen around for many yearsand are standardized. I f your program 
must interface with a language not mentioned in thischapter, do not despair. Check 
whether the language you are using calls functions in a manner similar to oneof the 
languages described here. 

Table 11.1 shows the types of routinesfor each language. T he major difference 
is that in FORTRAN a function returns a value, but a subroutine does not have a 
return value. W hen a function executes, a dummy variablewith thesamenameasthe 
function is created to hold the return value. (An example of this is shown in 
Listing 11.7, later in thischapter.) 
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Table 11.1. Routinetypes for different languages. 

Language Returns a value H as no return 

value 



assembly Procedure Procedure 

BASIC FUNCTION Subprogram 

C function (void) function 

FORTRAN FUNCTION SUBROUTINE 

Pascal Function Procedure 



DonotignoreyourC compiler'spower. Almost all C compilersproducea mixed 
(or perhapsa pure) assembly listing of th efu ncti on s being compiled. Typical assembly- 
listing options that you can use are shown in Table 11.2. 



Table 11.2. C compiler assembly-listing options. 



Option Description Compiler 



/Fa 


Produces an assembly 
output file 


M icrosoft 


/Fc 


Produces a mixed object 
and source listing file 


M icrosoft 


/Fl 


Produces an object 
listing file 


M icrosoft 


IS 


Produces a mixed 
assembly/source listing 
file 


Borland C++ 


WDISASM 
(a stand-alone 
program) 


Produces (with options) 
assembly/object listing 
files 


W atcom 
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If you use the options listed for M icrosoft compilers, you must use the full 
compiler, not QuickC or QuickC for Windows. N either of the QuickC compilers 
produces an assembly or object listing. 

Watcom'sutility (wdi sasm) hasanumberof optionsdocumentedinthemanual. 
It can disassemble .0 BJ files produced by any M icrosoft compatible compiler (one 
that produces compatible. OBJ files). You must check that thedisassembly iscorrect, 
however, becausenotall .OBJ filesdisassemblecorrectly. Sometimes, disassembly by 
hand (along and tedious process) istheonlywayto find out what thecompiler did for 
a given block of code. 

Do not overlook using theD OS debug commandtolookat.EXE and .OBJ files. 
Ithasacrudedisassembler, and itcan help you seewhatishappening. M ost debuggers 
can provide a disassembly listing as well. 

Some compilers (such asWatcom'sC/386) do not provide an assembly listing, 
but do comewith a utility program to produce assembly. I n W atcom, for example, the 
wdi sasm utility disassembles an .OBJ file. 

You can save hours of programming if you use the compiler's assembly listing 
option to produce an assembly program that iscompatiblewith C programs. You can 
savetimealsoifyou already know theargumentsthatarepassed to thefunction. Create 
a dummy function with as much of the necessary functionality as possible, then use 
the output of the compiler's assembly listing as the starting poi nt for your assembly 
routine. 



Assembly 

Assembly is not a language. Rather, it is a method to use the C PU 's native machine 
language. You must specify everything when writing in assembly: wheredata objects 
come from, where they will go, the basic operations, and so on. To use assembly 
language, you must be very familiar with how the CPU works. 

Listing 11.1, CALLASM , is a simple example of how assembly works. It is 
written in assembly, and can be linked with theC libraries. 
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Listing 11.1. CALLASM.ASM. 



CAL L AS M. ASM: This program cal Is the C printf() function 
and prints a string on the terminal. 



pr i nt f ( ) 



DGROUP 
TEXT 



ma i n : 



pr i nt f ( ) 



TEXT 
DATA 



NAME CAL L AS M 
EXTRN _pr i ntf : BYTE 



EXTRN 



acrtused: BYTE 



GROUP _ DATA, CONST, _ BSS 

SEGMENT WORD PUBLIC ' CODE' 

ASSUME CS: _ TEXT, DS: DGROUP, SS: DGROUP 

PUBLI C _ ma i n 

mov word ptr nCount , 0000H 

mo v ax , of f s et DGROU P: s z Buf f e r 

push ax 

mov ax, of f set DGROUP: LI 

push ax 



call near ptr _ p r i ntf 
add s p , 0 00 4 H 

mov word ptr nCount.ax 



ENDS 

SEGMENT WORD PUBLIC ' DATA' 



Prototype for 

Used to initialize C 

startup code 
Establ i sh the DGROUP 
N a me the code 

segment TEXT 

Our function is 

ma i n ( ) 
Initialize n Co u n t to 

zero 
Get address of 

sz Buf f er [ ] 
Push on stack as the 

I ast \ par a met er to 

Get f o r ma t string 

address 
Push on stack as the 

next parameter to 

pr i nt f ( ) 
Now call pr i nt f ( ) 
Di scar d pr i ntf ( ) ' s 

par a met er s 
Save pr i nt f ( ) ' s 

return value 
Done, return to 

cal I er 



Set up the data 
segment 

continues 
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Listing 11.1. continued 



sz Buf f er 

nCo u n t 
DATA 



PUBLIC szBuffer 
PUBLIC n Co u n t 



PUBLIC is the s a me 

as C s 
extern variables 
szBuffer is a public 

n a me 

nCount is a public 
n a me 



LABEL BYTE 
DB 
DB 



"This is an assembly program." 



OaH, 00H 



LABEL BYTE 
DB 00H.00H 
ENDS 



append the \ n for 
newl i ne 

nCount, init to zero 



CONST 
LI 



CONST 
BSS 



BSS 



SEGMENT WORD PUBLIC ' CONST' 

LABEL BYTE 

DB " %s " , 0 0 H 



ENDS 

SEGMENT WORD PUBLIC 'BSS' 



ENDS 
END 



Our f o r mat string, a 
constant, in the 
CONST 
segment 



The BSS segment is 
used 

by C to find the 
stack and 
has other uses, 
i n c I u d i ng 

storage for global 

v a r i a b I es 

not initialized 

explicitly 

by the program 

End of our program 
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Nobody recommendsthatyou writean assembly program that callsC functions 
Instead, write the program asaC program, then call thefunctions coded in assembly 
from C . 



FORTRAN 

FORTRAN was the first programming language developed, although the first 
compilers were created by Grace H opper in the early 1950s. These compilers were 
simple and inefficient, and the "languages" they supported were never named. 

FORTRAN (short for FORmulaTRAN slation) can trace its roots to the early 
1950s, whenjohn Backusand Irving Ziller at IBM set outto develop a new computer 
languageforthesoontoberdeased IBM 704 computer. Thedevdopment team grew 
to many more members, and in April 1957, they completed the first FO RTRAN 
compiler. 

ThelBM 704 was thefi rst computer to implement floating point in hardware. 
U ntil that time, computers used software emulation to perform floating-point math. 

Atypical FORTRAN program isshown in Listing 11.2, DEMO. FOR. 
Listing 11.2. DEMO. FOR. 

* DEMO. FOR 

* A simple, typical FORTRAN program. This program 

* is equi val ent to the standard HELLO. C program. 

* 2 3 4 5 6 7 8 

program hello 

print *, 'Hello ( FORTRAN) ' 

end 
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Pascal 

Pascal is taught extensively at schools and universities, but has never caught on in a 
nonacademic environment, mostly dueto the lack of good compilers. Apple released 
a U CSD Pascal system for theApple 1 1 , but the implementation wascrudeand almost 
impossible to use productively, requiring a custom operating system incompatible 
with theexisting Apple 1 1 operating system. Pascal became popular on PCsdueonly 
to the efforts of Borland, who released a good and inexpensivecompiler called Turbo 
Pascal. 

Although Pascal is still used today (and some Pascal compilers, most notably 
Turbo Pascal, remain), you will seldom see libraries of Pascal codethatyou will want 
to include in your C application. It is more likely you will have to convert a Pascal 
program to C . T reconversion iseasier if you can call Pascal functionsfrom theC code, 
and convert each function one at a time. A typical Pascal program is shown in 
Listing 11.3. 

Listing 11.3. HELLO. PAS. 

/* HELLO. PAS 

* A simple, typical Pascal program. This program 

* is equivalent to the standard HELLO. C program. 

*/ 

program hello 
begi n 

wr i t e I n ( ' Hello, from Pascal'); 

end. 



The example program looks very much like a C program. The comments are 
delimited in thesamemanner (using/ * and * / ), statements end with a semicolon, and 
the begin and end keywords are similar to braces in C . 
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BASIC 

BASI C (Beginner'sAII-Purpose Symbolic I nstruction C ode) isthefirst languageused 
by most beginning programmers. 1 1 issimpleand easy to learn, but not used for serious 
programming dueto its limitations. 

There are few reasons to interface BASIC code with C and even fewer methods. 
Several BASIC compilersareavailable,butnoneproducecodecompatiblewithC code 
created with a C compiler. The best way to interface BASIC and C is to convert the 
BASIC code to C, producing a new program that is bound to be better than the 
original. 

A simple BASIC program is shown in Listing 11.4, HELLO. BAS. It's the 
shortest example of a hello program! 

Listing 11.4. HELLO. BAS. 

PRI NT " H e I I o" 



Calling Other Languages from C 

U sually, you write the main body of your program in C . Then you may use a few 
functions written in another language because you want to enhance the speed of the 
program (assembly code can be much faster than code written in a higher level 
language) or because you do not want to rewrite thefunctions in C. 

This section describes how to create a basic C application and how to call a 
function created in another language. First, themain program iscreated in C , as shown 
in Listing 11.5, CALLN OTC.C. This program calls a non-C function called max( ) 
to determinethe maximum of two numbers. 

Listing 11.5. CALLNOTC.C. 

/* CALLNOTC program, written 1 9 9 2 by Peter D. Hipson */ 
Listing 11.5./* This C program calls C, FORTRAN, or assembly */ 

continues 
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Listing 11.5. continued 



#i nc 
#i nc 
#i nc 
#i nc 
#i nc 



u d e <st di o. h> 

u d e <st ddef . h> 

u d e <st d I i b. h > 

u d e <st r i ng. h> 

u d e <t i me. h> 



i n t cdecl maximum(int nVarl, i n t n V a r 2 ) ; 

i n t ma i n ( ) 

{ 

i nt nVar 1 = 0; 

i nt n V a r 2=1; 

char szBuf f er[ 256]; 

pri ntf("Enter the same number twice to e n d \ n " ) ; 

whi I e( nVarl ! = n Va r 2 ) 

{ 

pri n t f ( " Enter two integers, separated with blanks"); 
get s ( s z Buf f e r ) ; 

sscanf(sz Buffer, " %d %d", &n Va r 1 , &n Va r 2 ) ; 

pri ntf( "The values entered are %d and %d . The larger is %d \ n " 
nVar 1, 
nVar 2, 

ma x i mu m( nVa r 1 , n Va r 2 ) ) ; 

} 

r et u r n ( 0 ) ; 

} 



/ * This is maxi mum( ) wr i 1 1 en in C */ 
i nt maxi mum( 
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i nt nVar 1, 
i nt nVar 2) 



if ( nVar 1 < nVar 2) 

{ 

r et u r n ( n Va r 2 ) ; 

} 

else 

{ 

return) nVarl) ; 

} 

} 

In the max i mum( ) function, four lines of code do most of the work: a compare 
and two return values. M any programmers consider multireturnsin asinglefunction 
to be poor programming style. I do not agree, but I donotusegoto except to a single 
label near the end of the function just before the clean up code. 

To see what atypical C compiler does with themaxi mum( ) function, look at the 
following output from the M icrosoft C 7.00 compiler (without optimization): 



ma x i mu m: 



*** 00008a 


55 




push bp 




*** 00008b 


8b 


ec 


mo v b p , s p 




*** 0 0 0 0 8 d 


81 


ec 00 00 


s u b 


sp, OFFSET 


*** 000091 


56 




push si 




*** 000092 


57 




push di 




Line 50 


i f 


( nVar 1 < 


n Va r 2 ) 




*** 000093 


8b 


4 6 0 6 


mov ax, WORD 


PTR 6[ bp] 


*** 000096 


39 


4 6 0 4 


cmp WORD PTR 


4 [ bp] , ax 


*** 000099 


7c 


03 e9 00 


00 j ge 


L00387 


Line 51 


{ 








Line 52 




return! n Va r 2 ) ; 




*** 0 0 0 0 9 e 


8b 


4 6 0 6 


mov ax, WORD 


PTR 6[ bp] 


*** OOOOal 


e9 


0 0 0 0 


j mp L00386 




Line 53 


} 








Li ne 54 


else 






*** 0 0 0 0 a 4 


e9 


0 0 0 0 


j mp L00388 





L00387: 



Line 54 else (continued...) 

continues 
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Listing 11.5. continued 



ne 55 
ne 56 

* 0 0 00 a 7 

* OOOOaa 
ne 57 



; Li 
Line 



Local 
; Line 



return(nVarl); 
8b 4 6 0 4 mov ax, WORD PTR 4[ bp] 
e9 00 00 j mp L00386 



} 



L00388: 



ne 58} 
58 (end of 



* OOOOad 

* OOOOae 

* OOOOaf 

* OOOObl 

* 0 0 00 b2 
Size: 2 

0 



5f 
5e 

8b e5 

5d 

c3 



e function, cleanup:) 
L00386: 

pop di 



pop si 

mo v s p , b p 

pop bp 

ret OFFSET 0 



N ext, M icrosoft C 'si ox (maximum optimize) switch wasturned on so that you 
could seewhat a compiler can do using maximum optimization. T hefollowing output 
was produced: 

_ ma x i mu m: 

*** 00007a 55 push bp 

*** 0000 7b 8b ec mov bp, sp 

; nVar 1 = 4 
; n Va r 2 = 6 

*** 0 0 0 0 7 d 8b 5 6 0 4 mov dx.WORD PTR [bp+4] ; nVa r 1 

*** 0 0 00 8 0 8 b 5e 06 mov bx.WORD PTR [bp+6] ; nVa r 2 

; | *** if ( nVar 1 < nVar 2) 

; Li ne 50 

*** 0 0 00 8 3 3 b da cmp bx, dx 

*** 0 0 00 8 5 7 e 0 5 j I e $ I 4 3 3 

* * * | 

* * * r et u r n ( nVa r 2 ) ; 
Line 52 

*** 0 0 00 8 7 8 b c 3 mov ax, bx 

*** 000089 5d pop bp 

*** 00008a c3 ret 
*** 00008b 90 nop 
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; I *** } 

; | * * * else 
; Li ne 54 

$14 3 3: 

■ I * * * { 

; | * * * return(nVarl); 
; Li ne 56 

* * * 0 0 0 0 8 c 8 b c 2 mo v a x , d x 

. I * * * j 

; I *** } 

; Li ne 58 

*** 0 0 0 0 8 e 5d pop bp 

*** 0 0 0 0 8 f c3 ret 

_ max i mu m ENDP 

TEXT ENDS 
END 

. | * * * 

; | *** // #e n d i f 

Notice that the optimized code is slightly smaller and abitmorecomplex. This 
code might be more difficult to debug, but this drawback is unimportant because 
code is seldom debugged at the machine-language level after optimization. 



Calling Assembly from C 

Can a programmer using assembly language write a smaller, faster function than the 
compiler? To test this, I wrote the ma x i mum( ) function in assembly. So that I would 
not be biased by looking at what the compiler produced for optimized code, I 
wrote the assembly function beforel produced thetwo listings of max i mum( ) shown 
in the preceding section. 

Listing 11.6 is my version of maxi mum( ) . It is a bit shorter and faster than the 
version from the compiler, even when the compiler version is fully optimized. 

Listing 11.6. MAXIMUM. ASM. 



A hand optimized assembly function for C. 
cmacros.inc are a handy group of macros that make 



continues 
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Listing 11.6. continued 



; writing C-compatible functions easier. 
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nc I u d e 



e:\wi nde v\ i n c I u d e \ c mac r os . i nc 



i n t ma x i mu m( i n t , i nt ) ; 

This version was optimized by hand for both 
minimum size and fastest execution. The 
c ompi I er ' s code is twice as long. 



DGROUP 
TEXT 



ma x i mu m: 



NAME MAXI MUM 

GROUP _ DATA 

SEGMENT WORD PUBLIC ' CODE' 

ASSUME CS : _ TEXT, DS: DGROUP, SS: DGROUP 

PUBLIC _maximum 

enter 0 0 0 0 H.00H 



mov ax, wor d pt r +6 H [ bp] 
c mp wo r d pt r +4 H [ bp] , ax 
j I e short L6 



mo v 



ax, wor d pt r +4 H [ bp] 



L6: 



TEXT 



nop 
leave 
ret 
ENDS 



; Handy label target. 



DATA 
DATA 



SEGMENT WORD PUBLIC ' DATA' 
ENDS 



END 
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In my version of ma x i mu m( ) , I used the enter and leave operands, which are 
useful for creating functions called by higher level languages such asC. 

One of the tested values is returned in ax. If the value in ax is the larger of the 
two values, ax does not need to be reloaded and can just return that value. Otherwise, 
the other value is placed in ax and then returned. 

Becausethisversion isoptimized by hand, it executes faster and makes better use 
of memory. For morecomplex functions, however, thisimprovement ismoredifficult 
to obtain. By breakingyour assembly codeinto smaller and smaller partsand analyzing 
theresultant code, you can beconfident that it will befaster without performing some 
extensive benchmarks. 



Calling FORTRAN and Pascal from C 

Writing maxi mum( ) in FORTRAN isan easy task, as shown in Listing 11.7. Optimi- 
zation is less of a concern in FORTRAN than in assembly because FORT RAN is a 
high-level language. Not all C compilers support FORTRAN functions 

Listing 11.7. The maximum() function in FORTRAN. 



* The C function maximum!) written in FORTRAN 



integer function ma x i mu m( nVa r 1 , n V a r 2 ) 
integer*2 nVarl, n V a r 2 

ma x i mu m = nVa r 2 

if (nVarl .gt. n V a r 2 ) maximum = nVarl 
end 



When thisfunction is called from C, the calling C program file must tdl theC 
compiler that thefunction is written in FO RT RAN .Thisisaccomplished by properly 
declaring the ma x i mum( i function: 

i n t _ _ f o r t r a n ma x i mu m( i n t , i n t ) ; 
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The call fails if the function is not declared correctly (using the _ _ f o r t r a n 
keyword) becauseof theway thattheargumentsarepassed to a FO RT RAN program's 
functions Except for the differences in languages, functions written in FORTRAN 
and in Pascal are handled the same way. 

Calling C Functions from Other Languages 

Theoppositeof calling from C afunction written in another languageiscalling from 
a second language a function written in C. There are several problems in doing this. 
For example, manyC library functions rely on theexecution of C initialization code, 
which may not be present when a program written in another language calls a C 
function. You can partially alleviate this problem in assembly by writing the 
program's main function in C, thereby forcing the assembly program to behave like 
aC program. 

A C program can grow quitelargewhen it is linked, so many programmers write 
in assembly to keep the program smaller. If the C function called from another 
language does not make any calls to C library functions, no library functions are 
included in the executable program. This makes the program smaller and eliminates 
thetask of ensuring that C has properly initialized itself. 

This section presents a few examples of other languages calling a C function. 
These examples use CALLNOTC.C (Listing 11.5), which was used also in the 
previous section. Themaxi mi ze( ) function is written in C (see Listing 11.8), and the 
main, calling program iswritten in another language. Because max i mi ze( ) doesnotcall 
any other functions, I did not have to address the issue of calling C's startup code. 
However, I have included the necessary mechanism to initialize C, in case you 
need it. 

Listing 11.8. MAXIMUM. C. 

/* MAX I MUM. C function, written 1 9 9 2 by Peter D. Hipson */ 

/* This is a C function called by FORTRAN or assembly */ 

#i nc I ude < s t d i o . h > 
#i nc I ude <st ddef . h> 
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#i nc I u d e <s t d I i b . h > 
# i n c I u d e <s t r i n g . h > 
#i nc I ude <t i me. h > 

i nt cdecl maximum(int nVarl, i nt n V a r 2 ) ; 



i n t ma x i mu m( 
i nt nVar 1, 
i nt nVa r 2 ) 



if ( nVar 1 < nVar 2) 
{ 

r et u r n ( n Va r 2 ) ; 

} 

else 

{ 

return( nVarl) ; 

} 

} 



Themaxi mum( ) function could be written in assembly, but someother function 
that must do special things such as interact with hardwaremighthaveto be written in 
assembly. 

CallingC from Assembly 

An assembly program can call a C function, subject to either of two conditions. One, 
the C library must be linked with the assembly program. Any C functions called 
(CALLN OTC, in Listing 11.5, callsseveral) areprocessed by library functions, whose 
references must be resolved. 

Two, theC library's startup codemust beincluded and called. W ith M icrosoft 
C, this is accomplished by linking with the necessary library (I used su bce. li b in 
developing CALLN OTC. ASM , in Listing 11.9) and defining the external symbol, 
a c r t u s ed . W hen thestartup codefrom theC library isexecuted, it properly initializes 
theC environment. 
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Listing 11.9. CALLNOTC.ASM. 



/* CALLNOTC program, written 1 9 9 2 by Peter D. Hipson */ 

/* This is an assembly program that calls FORTRAN or assembly */ 



#i nc 
#i nc 
#i nc 
#i nc 
#i nc 



u d e <st di o. h> 

u d e <s t ddef . h > 

u d e <stdlib.h> 

u d e <s t r i n g . h > 

u d e <t i me . h > 



i nt cdecl maximum! int nVarl, int n V a r 2 ) ; 

; Enable 386 instruction set 
. 386 

NAME cal I not c 

; maximum!), sscanf(), gets!), and printf!) are called 

EXTRN _ ma x i mum: BYTE 

EXTRN _ s s c a nf : BYTE 

EXTRN gets: BYTE 

EXTRN _ p r i ntf : BYTE 

; acrt used is used to initialize C at runtime 

EXTRN _ _ a c r t used: BYTE 

; The datagroup is _DATA (misc data), CONST (constants; 
; and BSS (uninitialized data) 



DGROUP 
TEXT 



GROUP 



DATA, CONST, BSS 



SEGMENT WORD PUBLIC US E 1 6 ' CODE' 
ASSUME CS: T E XT , DS : DGROU P , S S : DGROU P 



; The program's main function, called by C's startup code. 
; Microsoft C naming conventions require the underscore 
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; prefix. Other compilers may use an underscore 
; following the n a me . 

PUBLI C _ ma i n 

_ ma i n : push bp ; Start up, save registers, 

mo v bp.sp ; and get ready to run 

sub s p , 0 0 0 0 H 
push si 
push di 

; Initialize nVarl and n V a r 2 so that they are not the same! 



mov wor d pt r - 1 0 4 H[ bp] , 0 00 0 H 

mov word pt r - 1 06 H[ bp ] , 0 00 1 H 

; Call to p r i nt f ( s z Ms g 1 ) ; 

mov ax , of f s et DGROUP: s z Msg 1 

push ax 

call near pt r _ p r i n t f 

add s p , 0 00 2 H 

j mp near pt r Loo pi 

; Loop back to L oo pi 

Loopl: mov ax, offset DGROUP : s z Ms g 2 

push ax 

call near ptr _ p r i n t f 

add s p , 0 00 2 H 

lea ax, - 102H[ bp] 

push ax 

call near ptr gets 

add s p , 0 00 2 H 

lea ax, - 1 0 6 H [ bp] ; nVar 2' s address 

push ax 

lea ax, - 1 0 4 H [ bp] ; nVar r s address 

push ax 



continues 
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Listing 11.9. continued 



mo v 


a x , 


offset 


DGROUP: szScanFor mat 


push 


a x 








1 ea 


ax, 


- 1 0 2 H[ bp] ; szBuffer (auto 


push 


a x 








call 


nea 


r pt r 


_ s s c a n f 




^ A A 

a a a 


sp. 


0 0 0 8 H 






push 


wo r 


d pt r 


- 1 0 6 H [ bp] ; 


nVar 2 


push 


wo r 


d pt r 


- 1 0 4 H [ bp] ; 


nVar 1 


call 


nea 


r pt r 


_ ma x i mu m 




add 


sp. 


0 0 0 4 H 






push 


ax 








push 


wo r 


d pt r 


- 1 0 6 H [ bp] ; 


nVar 2 


push 


wo r 


d pt r 


- 1 0 4 H [ bp] ; 


nVar 1 


mo v 


ax, 


offset 


DGROUP: s z P r 


n t F o r ma t 


push 


ax 








cal 1 


nea 


r pt r 


_ p r i n t f 




add 


sp, 


0 0 0 8 H 









mo v 


ax, word pt r - 1 0 6 H [ bp] 






c mp 


word pt r - 1 0 4 H[ bp] , ax 






i e 


short Al 1 Do n e 


We are finished 




i mp 


near pt r Loo pi 


Go around another time 


Al 1 Done: 


mo v 


ax, 0000H 


A zero return code 




i mp 


near ptr Dummy 




Du mmy : 


pop 


di 


Clean up and go h o me 




pop 


s i 






mo v 


sp, bp 






pop 


bp 






ret 






TEXT 


ENDS 







DATA 



SEGMENT WORD PUBLIC US E 1 6 ' DATA' 
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s z Ms g 1 


1 A D E 1 

L A d b L 


D V T E 
D 1 1 L 










Ud 


"Enter the same number twice to 


end" 


, UAH, 


n n u 
U U H 


s z Ms g 2 


LABEL 


BYTE 










DB 


"Enter two integers, separated 


wi t h 


b 1 a n k s " 


, 00H 


szScanFormat 


1 A D E 1 

L A d L L 


QVTC 

d I 1 b 










DB 


"%d %d", 00 H 








s z P r i n t F o r ma t 


LABEL 


BYTE 










Ud 


"The values entered are %d and 


0/ A " 








DB 


"the larger is %d " , OAH, 00H 








_ DATA 


ENDS 










CONST 


SEGMENT 


WORD PUBLIC USE16 ' CONST' 








CONST 


ENDS 










BSS 


SEGMENT 


WORD PUBLIC USE16 'BSS' 








BSS 


ENDS 











END 



The program calls not only the C function (max i mum( ) ), but also a number of 
other library functions, including pri ntto , gets) ) , and scant ( ) . These functions 
form thebasic I/O fortheprogram.DOSI/O interrupt routinescouldhavebeen called 
directly, but because they do not do formatted I/O, the program would have to con- 
vert the typed characters to integer numbers and convert the numbers back to 
characters for output. 

To summarize, writethemain program in C (or another high-level language) if 
possible. Then write in assembly the routines whose speed or size is critical. When 
using an advanced compiler (such as M icrosoft'sC 7.0), you can control how much 
of the library code is included, the arrangement of the program's segments (whether 
there are separate data and code segments or a single segment for both), and the 
allocation and use of memory. 

W hen programming on a PC (under D 0 S), do not forget the available DOS 
services. These services, listed in Tablell. 3, areaccessed usingthei nt 21 instruction. 
If you are using a different operating system, it should have similar functions. 
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Table 11.3. MS-DOS Int 21 function codes. 

Function Function DOS 



(nexj 


(aecimai; 


u escnption 


versi on 


00H 


0 


i erminate trie current 
program or process. 


1.U+ 


01H 


i 


Read a character from 
the console (with echo 
to screen). 


1.0+ 


02H 


2 


Write a character to the 
screen. 


1.0+ 


03H 


3 


Read a character from AUX:. 


1.0+ 


04H 


4 


Write a character to AUX:. 


1.0+ 


05H 


5 


Send output to the printer. 


1.0+ 


06H 


6 


Perform I/O from the 
console; DOS does not 
process the characters. 


1.0+ 


U / n 


7 


u q d ll Idl dLlcl 1 1 Ul 1 1 LI lc 

keyboard, waiting for a 
keypress if no character 
is available; the character 
is not processed by DOS. 


l.VJT 


08H 


8 


G et a character from the 
keyboard, waiting for a 
keypress if no character 
is available. 


1.0+ 


09H 


9 


Print a string to the 
console; the string is 
terminated with a dollar 
sign. 


1.0+ 


OAH 


10 


Read a character string 
(a line, typed by the 
user, up to a carriage 
return) from the keyboard. 


1.0+ 
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Function 
(hex) 


Function 
(decimal) 


Description 


DOS 
version 


OBH 


n 


Test to see whether a 
character is available 
from the keyboard. 


1.0+ 


OCH 


12 


Discard the contents of 
the input buffer, and get 
the input. 


1.0+ 


0 DH 


1 3 


Reset the soecified disk 
drive. 


1.0+ 


OEH 


14 


M ake the specified drive 
the current drive. 


1.0+ 


OFH 


15 


0 pen a file. 


1.0+ 


10H 


16 


Close a file. 


1.0+ 


1 1 H 


17 


Find the first filemeeting 
the provided specification. 


1.0+ 


12H 


18 


Find the next file after 
using i n t oxii. 


1.0+ 


13H 


19 


Delete the specified file. 


1.0+ 


14H 


20 


Perform a sequential read. 


1.0+ 


15H 


21 


Perform a sequential write. 


1.0+ 


16H 


22 


Create a new file. 


1.0+ 


17H 


23 


Rename a file. 


1.0+ 


18H 


24 


Reserved. 




19H 


25 


Get the current drive. 


1.0+ 


1AH 


26 


Set the Disk Transfer 
Address (DT A). 


1.0+ 


1BH 


27 


Get the current default 
drive data. 


1.0+ 



continues 
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Table 11.3. continued 



Function 
(hex) 


Function 
(decimal) 


Description 


DOS 

version 


1CH 


28 


Get data for the specified 
drive. 


2.0+ 


1DH 


29 


Reserved 




1EH 


30 


Reserved 




1FH 


31 


Reserved 




20H 


32 


Reserved 




21H 


33 


Random file read. 


1.0+ 


22H 


34 


Random file write. 


1.0+ 


I in 


i b 


U cl lllc bl£c Ul LI It: 

specified file. 


l.ut 


24H 


36 


Set thefile's current 
position. 


1.0+ 


25H 


37 


Set an interrupt vector. 


1.0+ 


26H 


38 


Create a new Program 
Segment Prefix (PSP). 


1.0+ 


27H 


39 


Random block read. 




28H 


40 


Random block write. 


1.0+ 


29H 


41 


Parse a filename into a 
valid DOS filename 


1.0+ 


2AH 


42 


Get the date. 


1.0+ 


2BH 


43 


Set the date. 


1.0+ 


2CH 


44 


Get the time. 


1.0+ 


2DH 


45 


Set the time. 


1.0+ 


2 E H 


46 


Set the write verify flag. 


1.0+ 


2 F H 


47 


Get the Disk Transfer 
Address (DT A). 


2.0+ 
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Function 
(hex) 


Function 

1 UII\aU VII 

(decimal) 


Description 


DOS 

version 


30H 


48 


G et the DOS version 


2.0+ 


3 1 H 


4Q 


T prminafp-and-Stav-Rpqdpnt' 

1 tl 1 1 1 1 1 1 ULv Ul 1 \A ~J L Uy 1 \ CJl \A tl 1 L 

(TSR). 


2 0+ 


32H 


50 


Reserved 




3 3 H 
j j n 


S 1 

j i 


c. ct nr «¥t thp hrpak flan 

\J \JI JtL LI It; Ul v_jUI\ 1 IUU| 

and get the boot drive. 


2 0+ 


34H 


52 


Reserved 




35H 


53 


Get the interrupt vector. 


2.0+ 


36H 


54 


Get the drive allocation 
information. 


2.0+ 


39H 


57 


Create a directory. 


2.0+ 


3AH 


58 


Delete a directory. 


2.0+ 


3 BH 


59 


Set the current directory. 


2.0+ 


3CH 


60 


Create a file. 


2.0+ 


3 DH 


fi 1 

U 1 


O npn a filp 

1 U lilt. 


2 0+ 




U L 


r Incp a filp 

*w 1 UJ^ CI lilt. 


2 0+ 


3 F H 


63 


Read from a file (can also 
read from a device). 


2.0+ 


4 0 H 


fi4 

U 4 


W rifp to a filp I ran alcn 
read from a device). 


2 0+ 


41H 


65 


Delete a file. 


2.0+ 


42H 


66 


Set the file pointer. 


2.0+ 


43H 


67 


Get (or set) a file's 
attributes. 


2.0+ 


44H 


68 


IOCTL processing. 


2.0+ 


45H 


69 


Duplicate a file handle. 


2.0+ 


46H 


70 


Redirect a file handle. 


2.0+ 



continues 
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Table 11.3. continued 



Function 
(hex) 


Function 
(decimal) 


Description 


DOS 
version 


47H 


71 


G et the current directory. 


2.0+ 


48H 


72 


Allocate a memory block. 


2.0+ 


49 H 


7 3 


k 9 ease a memory diock. 


Z.Ut 


4AH 


74 


Resize a memory block. 


2.0+ 


4BH 


75 


Execute (run) a program 

lev cr \ 


2.0+ 


4CH 


76 


Terminate a process with 

dlclUIII LUUc ^ WIIILII Lclll 

be tested in a batch file). 


2.0+ 


4DH 


77 


Get the return code from 
a child process. 


2.0+ 


4EH 


78 


Find the first file. 


2.0+ 


4FH 


79 


Find the next file, after 
rinaing tnerirsr. rue. 


2.0+ 


50H 


80 


Reserved 




51H 


81 


Reserved 




52H 


82 


Reserved 




53H 


83 


Reserved 




54H 


84 


Get the verify flag. 


2.0+ 


55H 


85 


Reserved 




56H 


86 


Rename a file. 


2.0+ 


57H 


87 


Get (or set) thefile 
date and time. 


2.0+ 


58H 


88 


Get (or set) the 
allocation strategy. 


3.0+ 
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Function 
(hex) 


Function 
(decimal) 


Description 


DOS 
version 


59H 


89 


Get extended error 
information following a 
DOS error. 


3.0+ 


5AH 


90 


Create a temporary file. 


3.0+ 


5BH 


91 


Create a new file. 


3.0+ 


5CH 


92 


Lock (or unlock) a file 
region. 


3.0+ 


5DH 


93 


Reserved 




5EH 


94 


G et the machine name, get 
(or set) the printer setup. 


3.1+ 


5FH 


95 


Device redirection. 


3.1+ 


60H 


96 


Reserved 




61H 


97 


Reserved 




62H 


98 


G et the Program Segment 
Prefix (PSP) address. 


3.0+ 


63H 


99 


G et the DBCS lead byte 
only table. 


2.25 


64H 


100 


Reserved 




65H 


101 


Get the extended country 
information. 


3.3+ 


66H 


102 


Get (or set) the code page. 


3.3+ 


67H 


103 


Set thefile handle count. 


3.3+ 


68H 


10 4 


l ommit a rue. 


JJT 


69H 


105 


Reserved 




6AH 


106 


Reserved 




6BH 


107 


Reserved 




6CH 


108 


Extended open file. 


4.0+ 
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C ailing C from FORTRAN and Pascal 

A C function is called from a FORT RAN or a Pascal program in a manner similar to 
the way any other type of function is called from FORTRAN or Pascal. The main 
program must be told that the function is written in C (so that the parameters are 
passed properly), and C library functions must not be called. 

Because C is not the language of the main program, theC initialization code 
cannot be called, which meanstheC library functions cannot be called. This restric- 
tion can limit the usefulness of a C function; you may decidethat it iseaaer to write 
the entire program in one language. 

All theThings that Can Go Wrong 

When you mix languages in your programming, you can easily get things mixed up. 
M uch of thediscussion in thissection isspecifictoM icrosoft'sC compilers. H owever, 
other compilersoften behavein a similar manner. Borland'sC compilers, for example, 
offer similar methods for argument passing. 

Following are some of the more common things that can ruin your day: 

If you are calling a C function from another language, you musttdl the 
compiler the calling convention. You can tdl C that a function will be using 
FO RTRAN calling conventions, then call thefunction from a FORTRAN 
program without tdling the FORT RAN program that thefunction is 
written in C. If thefunction is written in C with C's calling conventions, 
however, the calling program must know this. 

W hen assembly is called from C , the parameters must be read from the 
stack in the correct order. A C function expects its arguments to be passed 
in right to left order. A FO RT RAN or a Pascal function expects arguments 
in a left to right order. 

A function using the C calling conventions expects its caller to clean the 
arguments from the stack. A FORTRAN or a Pascal function takes the 
arguments from the stack itsdf. 

Thevaluebang returned must bein thecorrect place. Generally, AX is 
used for 2-byte return values, and AX and DX are used for 4-byte return 
values. 
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The compiler modifies thefunction's name. If itisaC function, an under- 
score is added (either before or after the name, depending on the compiler) 
and its case is not changed. If it is a FO RTRAN or a Pascal function, an 
underscore is not added and the name is converted to uppercase. W hen 
calling C functions from assembly, the underscore is often forgotten, 
leading to unresolved references. 

When accessing a multidimensional array, C and Pascal vary the subscripts 
in row-major order. FORTRAN and BASIC vary them in column-major 
order. 

TheC array n Ar r a y [ 2 ] [ 1 o ] [ 2 o ] is typically n Ar r ay( 20, io, 2) in 
FORTRAN . 

In C, arrays are indexed from zero. In FORTRAN , arrays typically are 
indexed from one. In Pascal, the lower bound is specified by the program- 
mer. Exceeding the bounds of an array is common in mixed C/FO RTRAN/ 
Pascal code because the initial starting points for the bounds differ. 

Do not call C library code from a program that has a main procedure 
written in FORTRAN or Pascal. 

Do not call library functions from a function written in a language different 
from the language of the main program. It may be possible to call the main 
program language's library functions, but make sure that you usethecorrect 
calling conventions. 

I n all, mixed language programming is not used frequently. It is complex and 
proneto subtlefailuresthat may bedifficultto find and correct. M ixed languagepro- 
gramming should be used as a last resort. 

Looking at Data 

Each programming language views data a little differently. Table 11.4 is a cross- 
reference of simple data types used in C, BASIC, FORTRAN, and Pascal. The 
similarity in the data types of FORTRAN and Pascal shows the common roots 
between those two languages. 
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Table 11.4. Data types. 



C/C++ BASIC FORTRAN Pascal 



short 


vari abl e % 


1 NTEGER* 2 


1 NTE G E R2 


i nt 


1 NTEGER 




1 NTEGER 


unsigned short 


(unsi gned l"IOt 

supported) 


(unsi gned l"IOt 

supported) 


WORD 


unsi gned (see 
unsigned long 
and unsi gned 
short ) 








long 


vari abl e & 
LONG 


1 NTE GE R* 4 

i nteger ^aerauit; 


1 NTEGER4 


unsigned long 


(unsigned not 

supported) 


(unsigned not 

supported) 


(unsigned not 

supported) 


float 


vari abl e ! 
vari abl e 
SI NGLE 


REAL * 4 
REAL 


REAL 4 
REAL 


do u b 1 e 


vari abl e # 
DOUBLE 


REAL * 8 

DOUBLE PRECI SI ON 


REAL 8 


1 ong doubl e 








unsigned char 




CHARACTER* 1 

(not the same 

aSLOGI cal) 
LOGI CAL *2 
LOGI CAL *4 


CHAR 



BecauseBASIC does not p red eel are scalar variables, avariable'stypeisindicated 
by a suffix code (%, &, \ , or #). If the suffix is missing, the variable is assumed to be a 
real (floating-point) variable. 
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Variables are classified according to 

• Type (what is stored in them), such as integer, character, or floating point 

• Size (how large they are) 

I f you pi ctu re a vari abl e as a certai n n u m ber of bytes h ol d i n g a certai n type of data, you 
can easily convert from one language's variable types to another. 

Names and Limits 

C allows a longer name length (the number of characters in a name that are signifi- 
cant) than FORTRAN. In C, the limit is 32 characters for internal names and 6 
characters for external names. With some versions of FO RTRAN , the limit is 6 
characters for internal or external names. 

When an external name is processed byC compilers, an underscore is usually 
added beforeor after thename. When programming in languagesthatdonotusethis 
convention, you must explicitly add the underscore. In Listing 11.9, for example, the 
printto library function is called. The referenced name is _pr i ntf because the 
compiler prefixes the name with an underscore, and you must do the same. A 
FORTRAN or Pascal identifier does not have an added underscore. 

W hen an external identifier isused in FO RT RAN , thecaseof thenamewill have 
been changed to uppercase. This can create problems when linking the program, 
depending on the linker's options. Ifyou usethe/Noi gnorecase option (which tells 
thelinker that thecaseof theidentifiersmustmatch) when you createa mixed language 
program, thelinker may generate unresolved referenceerrorsfornamesin thewrong 
case. 



Summary 

In this chapter, you learned about mixed language programming. 

• Programs written in C can call functions written in assembly, FORTRAN, 
Pascal, and BASIC, provided the compiler supports mixed language calls to the 
language to be called. 
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• A function written in C can be called from other languages. When a C func- 
tion is called from an assembly program, library functions can be called 
provided theC startup code is incorporated into the assembly program. If the 
other language is not assembly, however, theC library functions cannot be 
used. 

• You must consider how each of the variable types, especially arrays, are 
handled between C and other languages. D o not exceed the bounds of an 
array. Arrays in FORTRAN are indexed starting with one; arrays in C are 
indexed starting with zero. 

• TheFORTRAN compiler converts all external identifiers in FO RT RAN 
programs to uppercase. C and assembly external identifiers can be mixed case. 

• Arguments for a C function are placed on the stack in the opposite order of 
arguments in FO RT RAN or Pascal. 

• With mostC compilers, it is easy to write theshell of an assembly function in 
C , compile it with an assembly listing option, and convert the assembly listing 
to an assembly file. This ensures that the parameters, calling protocol, and 
return values are correctly coded. 
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Computers generally do two things: number management and data management. 
M ostend users(nonprogrammers) managedata or numbers, and most of thesoftware 
tools they use are related to these two tasks. 

N umbermanagementisusuallyperformedusingaspreadsheetprogram.Spread- 
sheetsarecomplexprogramsthatenablea person to manipulatenumeric data, generate 
what-if scenarios, create reports, and so on. Because spreadsheet programs have 
become standardized, there are a limited number of add-on products. 

W ith data management systems, the story is different. M any custom add-on 
programs directly interact with the database program and with files created with the 
database program. 

This chapter covers the interaction of C programs with database programs and 
the use of the data files created with database programs. W hen the name d BASE is 
mentioned, theinformation usually appliesto most other compatible programs, such 
asFoxBase. 
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Products such asR:Baseand 0 racleareincompatiblewith dBASE. You can write 
callable C functions for use with R:Base, but the real power when using R:Base files 
comes from a library of functions (avail able from M icrorim, which supplies R:Base) 
that allow C programs to access R:Base database files using the same command 
functionality as the R :Base interactive commands 

I nterfacing with dBASE -C ompatible P rograms 

The primary way to interface with database programs is with Clipper, a dBASE- 
compatible compiler (just like a C compiler). Clipper is not a C compiler, however, 
so some of the calling conventions are different. 

For example, a C function called from a Clipper program (Summer 1987 
version) does not receive its arguments directly. Clipper places the arguments in 
external variables, and thecalled function must make assignments from these external 
variables. 

Becausethereareno interfacing standards, theproceduresfor interfacing C with 
adatabaseprogram differ depending on theproduct. Knowing how to interfaceC with 
dBASE, for example, will not help you interfaceC with Clipper, FoxBase, or Paradox. 

UsingdBASE Files Directly 

Rather than using Clipper, dBASE, or another database program to access a dBASE 
file, itismorecommon toincludein aprogramthesupporttodirectlyaccessadBASE 
and dBASE-compatiblefile. 

There are three main versions of dBASE that you must work with. The 
dBASE 1 1 program is old and rarely used. dBASE 1 1 1 is more common, is still used 
extensively, and is the standard that other programs follow when creating a dBASE- 
compatiblefile. ThedBASE IV program isthelatest of thedBASE programsthatyou 
might encounter. ThischaptercoversdBASE III anddBASE I V's f i I e f eatu res th at are 
compatible with dBASE III. 

Accessing afilecreated by dBASE is as easy as accessing any other file. Theformat 
of asimpledBASE fileisshown in Figurel2.1. Thisfigureshowsthelayout of thefile 
header, the column headers, and the data. 
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Beginning of the file. 

File header (DB3HEADER) 

Field header #1 (COLUMNDEF) 

Field header #2 (COLUMNDEF) 

Field header #3 (COLUMNDEF) 

; I (additional field headers, as 

| required) 

Field header #n (COLUMNDEF) 

End of header marker (OxOD) 



k Data records through the end 
of the file. 



Figure 12.1. A dBASE file. 



Thischapter doesnot describethespecial featuresof dBASE IV or how to access 
indexes. Bytheend of thischapter, however, you should beableto read adBASE file 
and create a file that dBASE can read. 

The dBASE file format is simple. Using a program such asDUM P, you could 
easily dump a simple dBASE fileand determine the use of each filevariable. So that 
you do not haveto do this, however, thissection describesthetwo structures that make 
up the file's header. 

The first structure (called db3header in Listing 12.1) defines thefileheader and 
describes the dBASE file. This information enables you to determine the file's 
contents, such asthefile's record layout, thenumberof recordsin thefile, thedatethe 
file was updated, and the version of dBASE that created thefile. 

#p r a g ma pack 1 /* Pack to byte boundaries */ 
t ypedef struct { 

/* Bit fields are arranged from least significant 



to mo s t s 
unsi gned 
u n s i gned 
unsi gned 
unsigned char 
unsigned char 
long i n t 
short i n t 
short i n t 



g n i f i cant * / 



bf Ve r s i on: 7 ; 
bf Ha s Me mo : 1 ; 
b Yea r : 8; 
bMont h; 
b Da y ; 

I Nu mbe r Re c o r d s ; 

n F i r s t Rec o r d Of f s et ; 

nRecordLengt h; 
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unsigned char s z Res er ve d[ 2 0] ; 
} DB3HEADER; 

The main header structure has a series of bitfield variables. This allows a direct 
test of the memo field bit, which is otherwise difficult to access, as follows: 

unsigned short int bfVersi on: 7; 

Thebfversi on variable is a 7-bit bitfield. Its value designates the version of 
dBASE that created the database file. For most dBASE-compatiblefiles, bf version 
contains one of the values in Table 12.1. 



Table 12.1. Version codes for dBASE-compatiblefiles. 


Filetype 


Description 


0x02 


dBASE II file. Generally incompatible with dBASE III. 


0x03 


dBASE III or FoxBase file. The file could have been created 




with dBASE IV, but thefile is compatible with dBASE III. 


0x04 


dBASE IV file, partially compatible with dBASE III file I/O 




routines. 


0x75 


FoxBase file. Thememo file bit is usually set (see discussion 




Of bf HasMemo ). 


OxOB 


dBASE IV file. Memo file bit is usually set (see discussion of 




bf Ha s Me mo ). 



Generally, a value of 3 in the version field (bf ver si on) means that thefile is 
compatible with dBASE III. If thebf Has Memo variable (a single bit) isTrue, a.DBT 
memo file is included: 

unsigned short int bf Ha s Me mo : 1 ; 

T hefunctionsin thischapter do not accessmemo files, so thisbit and any memo fields 
can be ignored. 

ANSI standards requirea bit field to bedefined asa short int, sothebYear byte- 
sized variable(theyear that the database was last updated) isincludedasthefinal eight 
bits in the bit field: 

unsigned short int b Y e a r : 8 ; 
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Thispreventsusfrom taking theaddressof thisvariable, butwenever need its address. 
(If weneeded theaddressof b Year , wecould definea union to map a variable to this 
address.) 

T he b Month byte variable contains the month the database was last updated: 

unsigned char b Mo nth; 

T he b Da y byte variable contains the day the database was last updated: 

unsigned char b Da y ; 

Thei Number Recor ds variable contains the number of database records in the 
database. T he program uses this value to determine how many records must be read. 

long int I NumberRecords; 

The number of fields in each record and the location of the first record is 
computed with the n f i rst Recor dot f set variable: 

unsigned short int n F i r s t Re c o r d Of f s et ; 

Becauseafileseek operation requiresai ong type, you must cast this variableto a i ong . 
A short int is used because a dBASE header is never more than 64K. 

ThenRecordLengt h variable holds the length of each record in thedatabase: 

short int nRecordLength; 

T h e f i rst byte of each record isaflag field. Thisflag field containsa blank if the record 
is not deleted, or * if it has been deleted. 

The reserved fields should not be used or modified. Generally, they contain 

zeros: 

unsigned char s z Res e r v ed [ 2 0 ] ; 

After the header is read, the column definition records (often called field 
definition records) can beread.T hereisonecolumn definition record for each column 
in thedatabase. 

You usually do not know how manycolumnswill be defined in a database when 
you write your program (and pleasedo not guess a "really large number"). Therefore, 
the program must compute the number of column definitions by reading the 
information in the file header. 
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Each column definition is contained in a structure as shown: 



t y pedef struct 
char 
char 
I ong 

unsigned char 
unsigned char 
char 

} COLUMNDEF; 



s z Co I u mn Na me [ 11] 
c h T y pe; 

I Fi el dPoi nt er ; 
b y L e n g t h ; 
by Dec i ma I PI ace; 
s z Res er ved [ 14] ; 



The first field, szcoi umnName, contains the name of thecolumn asastandard C 
string (terminated with \0). This name may be up to 10 characters long, leaving a 
final 11th byte to hold the terminating \0. 

char szCol umnName] 11] ; 

Thecolumn type is coded in the single character member called chType: 

char chType; 

Thiscodecan contain any of thecharacters shown in Tablel2.2. Thefield definition 
characters in Table 12.2 are valid for dBASE III. For other versions of dBASE, other 
fields may be defined. 



Table 12.2. dBASE column definition characters. 



Value Identifier 



Description 



N U ME Rl C_ F I ELD 

CHARACTE R_ F I ELD 
LOGI C AL _ F I ELD 

MEMO FIELD 



DATE FIELD 



Thefield isa number, either integer (if the 
decimal places are 0) or floating point. 

Thefield is a character string. 

Thefield islogical, containing y , y, n, n, 

t, t , f, or f 

Thefield isa pointer to a 512-bytememo 
field in the.DBT file, so the file position is 
computed as 512 times the field's value. A 
memo field has a fixed length of 512 bytes. 

Thefield is a date formatted as 
YYYYM M DD. 
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Value Identifier Description 

f float field Thefield isa floating-point number. (N ot 

found in all database programs because this 
type is not dBASE Ill-compatible). 

p picture field Thefield isin pictureformat. (Not found 

in all database programs because this type is 
not dBASE Ill-compatible.) 



Thei Fi ei dPoi nter member is used by some versions of dBASE asthedisplace- 
ment of thefield in the record: 

long I Fi el dPoi nter; 

Because you should not depend on this field being set, thefield offsets are 
computed based on the sizes of the previous fields. For most versions of dBASE, 
i Fi ei dPoi nter is initialized to zero. M anyprogramsthatcreateadBASE-compatible 
file use this field for their own purposes— whether this isa good idea is up to you, the 
programmer. 

ThebyLengt h member contains the length of thefield: 

unsigned char byLength; 

This length is the only indicator of where one field ends and the other begins. The 
sum of byLengt h for each column, plus 1 for the record status byte, equalsthefile 
header's n Rec o r d l en g t h member. (T herecord status byte is also called theddeted flag 
byte and isthefirst byte in every record.) 

The program uses the byDeci ma i pi ace member to determine theformat of the 
numbersin thecolumn. If the valueof byDeci ma i pi ace is zero, thenumbersin the 
column areinteger. If the value is greater than zero, the numbers are floating point. 
Becausedecimal places are stored in the database, you can usesimplescanf ( ) calls to 
read thecolumn'svalue. If necessary, thecolumn'svaluecan be saved for later display 
of the number. 

unsigned char byDeci mal PI ace; 

Finally, 14 bytes of space in thecolumn definition are unused and marked as 
reserved. You should not use these bytes: 

char s z Res er ved [ 1 4] ; 



473 



Part III • Working with Others 



Reading dBASE and dBASE-Compatible Files 

ReadingdBASE-compatiblefilesisasimpleprocess. T hesefilesconsist of afileheader, 
column headers, and data. They are organized in a fixed manner, have a simple 
structure, and have data that is generally in an ASC 1 1 format, easily read into a set of 
variables using sscanfi ) function calls. 

ToreadadBASE file, you need onlyasimpleprogram. Listingl2.1, D BREAD. C, 
reads a dBASE III file and prints each record's raw data to the screen. 

Listing 12.1. DBREAD.C. 

/* DBREAD, written 1 99 2 by Peter D. Hipson */ 
/* This program reads dBASE III files. /* 

#i nc I u d e < s t d i o . h > 
#i nc I u d e <st ddef . h> 
#i n c I ud e <s t d I i b . h > 

/* So me defines useful for dBASE files: */ 

/* Actual record status defines (first byte of each record) */ 
#def i ne DELETED_ RECORD ' *' 
#def i ne USAB L E_ RECORD ' ' 

/* Field (column) definitions (capital letters, please) */ 



#def 


ne 


NUMERI C _ F 1 ELD 


' N ' 


#def 


ne 


CHARACTE R_ F 1 ELD 


' C 


#def 


ne 


LOGI C A L _ F 1 ELD 


' L' 


#def 


ne 


MEMO. Fl ELD 


' M' 


#def 


ne 


DATE _ F 1 ELD 


' D' 


#def 


ne 


F L OAT_ F 1 ELD 


' F' 


#def 


ne 


PI CTURE FIELD 


' P' 



/ * End of dBASE defines */ 

fpragma pack(l) /* Pack to byte boundaries */ 

t y pedef struct { 
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Bitfields are arranged from least significant to most significant */ 

unsigned int bfVersi on: 7; 

unsigned int bf Ha s Me mo : 1 ; 

unsigned int b Y e a r : 8 ; 

unsigned char b Mo nth; 

unsigned char b Da y ; 

long int I NumberRecords; 

short int n F i r s t Rec o r d Of f s et ; 

short int nRecordLength; 

unsigned char s z Res er ve d[ 2 0 ] ; 



■1 



} DB3 HEADER; 



t ypedef struct { 

char s z Co I u mn Na me [ 1 1 ] 

char c h T y pe; 

long I FieldPoi nter; 

unsigned char byLength; 

unsigned char byDeci mal PI ace; 

char s z Res er ved[ 1 4] ; 
} COLUMNDEF; 



int ma i n ( ) 
{ 

FILE * DBF i I e; 
DB3HEADER db3Header; 
COLUMNDEF *Col umnDef ; 
unsigned char * pBuffer; 
char s z F i I e N a me [25]; 



nt 
nt 
nt 



i ; 

nColumn Count = 0; 
nRes ul t ; 
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Listing 12.1. continued 

long I Cur r ent Record = 0; 

double dSal es = 0.0; /* Forces loading of floating point support.*/ 



pr i ntf ( " si zeof ( DB3HEADER) =%d\n", s i z e of ( DB3 HE ADE R) ) ; 
pri ntf ("si zeof ( COL UMNDEF ) =%d\n", s i z e of ( COL UMNDE F ) ) ; 

p r i n t f ( " Please enter customer database name: "); 

get s ( s z F i I e Na me) ; 

DBFile = fopen(szFileName, " r b " ) ; 

if ( DBFi I e == NULL) 

{ 

fpri ntf(stderr, 

"ERROR: File ' %s ' couldn't be opened. \ n " , s z F i I e N a me ) ; 

exi t ( 4) ; 

} 

nResult = f r e a d ( (char *) &db3Header , 
si zeof ( DB3HEADER) , 
1, 

DBFi I e) ; 

i f ( n Res u I t ! = 1) 

{ 

if ( ! f eof ( DBFi I e) ) 

{ 

f pr i nt f ( st de r r , "ERROR: File ' %s ' , read error (Database \ 
h e a d e r ) . \ n " , 

s z F i I e Na me ) ; 
f cl ose( DBFi I e) ; 
exi t ( 4) ; 

} 
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else 
{ 

fpri ntf(stderr, "Unexpected end of database file ' %s ' . \ n " , 
s z F i I e Na me ) ; 

f cl ose( DBFi I e) ; 

exi t ( 4) ; 

} 

} 

i f ( db3Header . bf HasMemo) 

{ 

pri ntf("There is a . DBT memo\ n " ) ; 

} 

else 
{ 

pri ntf("There is no a .DBT me mo \ n " ) ; 

} 

pri ntf( "Created with version %d of dBASE. \n", 
d b3 Heade r . bf Ver s i on) ; 

i f ( db3Header . bf Ver si on ! = 3 && 
db3Header . bf Ver si on ! = 4) 

{ 

pri ntf( "The version of dBASE that created this file " 
"may not be compat i bl e. \ n" ) ; 

} 

pri ntf( "Updated last on: %d/", d b 3 Hea d e r . b Mo n t h ) ; 

pri ntf ( "%d" , db3 Header . b Da y ) ; 

pri ntf ( ' 1 9 %d \ n " , d b 3 Hea de r . bYear ) ; 

pri n t f ( " There are %ld records in the database. \n", 
d b3 Heade r . I NumberRecords) ; 

pri ntf( "The first record starts at byte %d . \ n " , 
db3Header. n F i rstRecordOffset) ; 



pri ntf( "Each record is %d bytes long. \ n " 
db3Header. nRecordLength); 
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Listing 12.1. continued 

pri ntf("The reserved field contains ' %s ' \ n " , 
db3Header . sz Reser ved) ; 

nCol umnCount = 

(db3Header. n F i r s t Rec o r d Of f s e t - si zeof ( DB3HEADER) ) / 
si zeof ( COLUMNDEF) ; 

p r i n t f ( " T h e r e are %d columns in each record. \ n " , nCol umnCount ) ; 

/* Now allocate memory for each of the column definitions: */ 

ColumnDef = (COLUMNDEF *) cal I oc( si zeof( COLUMNDEF) r n Co I u mn Co u n t ) ; 

if ( Col umnDef == ( COLUMNDEF *) NULL) 

{ 

fpri ntf(stderr, 

"Couldn't allocate memory for the column definitions \n"); 
f cl ose( DBF i I e) ; 
exi t ( 4) ; 

} 

nResult = f r e a d ( (char *) Col umnDef, 
si zeof ( COLUMNDEF) , 
nCol umnCount , 
DBFi I e) ; 

if (nResult ! = n Co I u mn Co u n t ) 

{ 

if ( ! f eof ( DBFi I e) ) 

{ 

f pr i nt f ( st de r r , "ERROR: File ' %s ' , read error (Column \ 
d e f i n i t i o n s ) . \ n " , 

s z F i I e Na me ) ; 
f cl ose( DBFi I e) ; 
exi t ( 4) ; 

} 
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else 
{ 

fpri ntf(stderr, "Unexpected end of database file ' %s ' " 
" while reading column def i ni t i ons. \ n" , 
s z F i I e Na me ) ; 

f cl ose( DBFi I e) ; 

exi t ( 4) ; 

} 

} 

pri ntf( "Col umn definitions: \ n " ) ; 

for ( i =0; i < nCol umnCount ; i + + ) 

{ 

pri n t f ( " N a me : ' % 1 0 . 10s' ", Col umnDef[i ] . szCol umnName); 

swi tch( Col umnDef[ i ] . chType) 
{ 

case NUMERI C _ F I ELD: / * Number field */ 
pri n t f ( " ( N u me r i c ) \ n " ) ; 
break; 

case C HA RACT E R_ F I ELD: /* Character field */ 
pri n t f ( " ( C h a r a c t e r ) \ n " ) ; 
break; 

case LOGI CALFI ELD: /* Logical (using ' Y' , ' N' , etc */ 
pri n t f ( " ( L o g i c a I ) \ n " ) ; 
break; 

case MEMOFI ELD: /* Memo Index field */ 
pri n t f ( " (Memo file . DBT I ndex) \ n") ; 
break; 

case DAT E_ F I ELD: /* Date in YYYYMMDD format */ 
pri n t f ( " (Date in YYYYMMDD) \ n") ; 
break; 
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Listing 12.1. continued 



case FLOATFI ELD: /* Floating point field */ 
p r i n t f ( " (Floating p o i n t ) \ n " ) ; 
break; 

case PI C T U R E _ F I ELD: /* Date in YYYYMMDD format */ 
p r i n t f ( " (Picture f o r ma t ) \ n " ) ; 
break; 

default: /* Unknown type of field */ 
p r i n t f ( " (Field type unknown) \ n") ; 
break; 

} 

pri ntf( "Length: %d\n", Co I u mn Def [ i ] . by L en g t h ) ; 

p r i n t f ( " Dec i ma I P o i nt : %d\n", Co I u mn Def [ i ] . b y Dec i ma I P I a c e ) ; 

pri ntf( "Reserved '%s'\n", Col umnDef [ i ] . szReserved) ; 

} 

Next allocate the buffer to hold a database record 

We add a byte for the terminating \0, which is not supplied by 

d BAS E as part of the record. 



pBuffer = (unsigned char * ) c a I I o c ( s i z eo f ( c h a r ) , 
db3Header. nRecordLength + 1); 

if ( pBuf f er == (unsigned char * ) NULL) 

{ 

fpri ntf(stderr, 

"Couldn't allocate memory for the column buffer\n"; 

f cl ose( DBF i I e) ; 

exi t ( 4) ; 

} 

n Re s ul t = f seek( DBFi I e, 

( I ong) db3 Header . n F i r st Recor dOf f set , SEE K_ SET) ; 

if ( n Res u I t 1=0) 
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{ 

if ( ! f eof ( DBFi I e) ) 
{ 

fpri ntf(stderr, "ERROR: File ' %s ' , seek error. \n", 
s z F i I e Na me ) ; 



f cl o s e ( DBFi I e) ; 



exi t ( 4) ; 

} 

else 

{ 

fpri ntf(stderr, "Unexpected end of database file ' %s ' " 
" wh i I e reading record. \ n " , 
s z F i I e Na me ) ; 

f cl ose( DBFi I e) ; 

exi t ( 4) ; 

} 

} 

for ( I Current Record = 0; 

I CurrentRecord < d b 3 Hea d e r . I Nu mbe r Re c o r d s ; 
+ + I Cur r ent Recor d) 

{ 

n Res u I t = f r ead ( ( c h a r * ) pBuf f er , 

d b3 Heade r . n Rec o r dLe ngt h , 1, DBFi I e ) ; 

if ( n Re s u I t ! = 1) 

{ 

if ( ! f eof ( DBFi I e) ) 

{ 

f pr i nt f ( s t de r r , "ERROR: File ' %s ' , read error \ 
( records) . \ n", 

s z F i I e N a me ) ; 



f cl ose( DBFi I e) ; 



exi t ( 4) 

} 

else 
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Listing 12.1. continued 



fpri ntf(stderr, "Unexpected end of database file ' %s ' " 
" while reading records.\n", 
s z F i I e Na me ) ; 



f cl ose( DBF i I e) 
exi t ( 4) ; 



} 

} 



pBuffer [ db3Header . nRecordLengt h] = '\0'; 

Where we print inside the switch, a program that would use the 
database records would parse, and read each field, probably 
using a built for ma t string and a call to sscanf(). 



swi t ch( pBuf f er [ 0] ) 

{ 

case US A BL E_ RECORD: /* Valid, undeleted record */ 
pr i ntf ( " Recor d ' %s ' \ n" , &p Buf f er [ 1 ] ) ; 
break; 

case DEL ETED_ RECORD: /* Record has been deleted. Usually, 

you'd ignore it. */ 
pr i ntf ( " Del et ed ' %s ' \ n" , &p Buf f er [ 1 ] ) ; 
break; 

default: /* The record's status is unknown */ 
pr i ntf (" Unknown '%s'\n", &p Buf f er [ 1 ] ) ; 
break; 



} 

} 

r et u r n ( 0 ) ; 
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In D BREAD, first the file is opened, then the file header is read into the 
db3header structure. The information placed in this structure is used to read the 
column definitions and the data records. 

Next, theprogram allocates thememory for thecolumn definitionsby comput- 
ing the number of columns: 

n Co I u mn Co u n t = 

(db3Header. nFi rstRecordOffset - si zeof( DB3HEADER) ) / 
s i zeof ( COLUMNDEF) ; 

Thecal i oc( ) function usesthencoi umncount variableto allocate the required 
memory. Thecolumn definitions are saved for later use. 

Col u mn Def = (COLUMNDEF * ) c a I I o c ( s i z eof ( COL U MNDE F ) , nCol umnCount ) ; 

After the memory is allocated, the column definitions are read. A loop is not 
necessary; theprogram uses one read in which the number of bytes is computed from 
th e si ze of th e structu re an d th e n u m ber of col u m n s i n th e database: 

n Result = f r e a d ( (char *)ColumnDef, 
s i zeof ( COLUMNDEF) , 
nCol umnCount , 
DBFi I e) ; 

After all thecolumnshavebeen read (determined bythereturn valuefrom a call 
to thef r ea d ( ) function), theprogram can process them as required. In this simple 
example, theinformation is printed to thescreen. A f or ( ) loop isan easy and effective 
way to process the columns: 

for ( i = 0 ; i < n Co I u mn Co u n t ; i + + ) 

{ 

pr i nt f ( " Name: ' % 1 0 . 10s' ", Co I u mn Def [ i ] . s z Co I u mn Na me ) ; 

When the form at of the records has been determined, theprogram can process 
therecordsin thedBASE file. First, a buffer must beallocated to hold therecords. T he 
buffer'ssizeisknown (or can becomputed from thesizeof each record, not forgetting 
the byte for the record's status): 

pBuffer = (unsigned char * ) c a I I o c ( s i z eo f ( c h a r ) , 
db3Header. nRecordLength + 1); 

Becausewedo not usedBASE'sindex files, weaccept therecordsin theorder that 
they are stored in the file, using a simple fort ) loop. Before reading therecords, I 
recommend that you doaseektotheknown point wherethefirst record can befound. 
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This is necessary because dBASE adds a carriage return (OxOD) after the column 
definitions and may well add another extra byte. Thispointisfound in thefileheader, 

in the n f i rstRecordOff set member of the db3 heade r structure. 

n Re s ul t = f s e e k ( DBF i I e, 

( I ong) db 3 Header . n F i r st Re c o r d Of f set , SEEKSET) ; 

Theprogram isnow attheposition of thefirst record in thedBASE file, so it can 
read each record: 

for ( I Current Record =0; 

I Cur r ent Recor d < db3Header. I NumberRecords; 
++I Cu r r e nt Rec o r d ) 

{ 

n Res ul t = fread((char *) pBuf f er , 

db3Header . nRecor dLengt h, 1, DBFile); 

As each record isread, thefirst bytetellsyou thestatusof therecord. If thefirst 
byte is a blank, the record is not deleted. I f the byte is * , the record has been deleted 
and should not be processed (unless you are writing a deleted record processor!). 

Creating dBASE and dBASE -Compatible Files 

With alittlecare, you can read a dBASE fileor createadBASE-compatiblefilewithout 
difficulty. The process of creating a dBASE-compatiblefile is basically the reverse of 
reading a file. 

Listing 12. 2, D BW RITE. CisasimpleprogramthatcreatesasimpledBASE III- 
compatible.D BF file. T hisfilecan be read by any program that can read dBASE files. 

Listing 12.2. DBWRITE.C. 

/* DBWRITE, written 1 9 9 2 by Peter D. Hipson */ 

/* This program creates a dBASE - compat i bl e file. */ 

/ * Deri v e d from DBREAD. C */ 

#i nc I ude <st di o. h> 

#i nc I ude <st ddef . h> 

#i nc I ude <st d I i b. h > 

#i nc I ude <st r i ng. h> 

#i nc I ude <t i me. h> 
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/* Some defines that are useful for dBASE files: */ 



/* Record status defines (first byte of each record) */ 



capital letters, please) */ 



#d ef i n e 


DE L ETED_ RECORD 




#def 


ne 


USABLERECORD ' 




/* F 


el d 


( c o 1 u mn ) def i n 


t i o n s 


#def 


ne 


NUMERI C _ F 1 ELD 


' N ' 


#def 


ne 


CHARACTE R_ F 1 ELD 


' C 


#def 


ne 


LOGI C AL _ F 1 ELD 


' L' 


#def 


ne 


MEMO. Fl ELD 


' M' 


#def 


ne 


DAT E _ F 1 ELD 


' D' 


#def 


ne 


F L OAT_ F 1 ELD 


' F' 


#def 


ne 


PI CTURE FIELD 


' P' 



/ * End of dBASE defines */ 



#p r a g ma pack(l) /* Pack to byte boundaries */ 



t ypedef struct { 



Bit fields are 
unsigned i n t 
unsigned i n t 
unsigned i n t 
unsigned char 
unsigned char 
I ong i nt 
short i n t 
short i n t 
unsigned char 
} DB3 HEADER; 



arranged from least significant to most significant */ 

bf Ve r s i on: 7 ; 

bf Ha s Me mo : 1 ; 

b Yea r : 8; 

bMont h; 

b Da y ; 

I NumberRecords; 
n F i r s t Rec o r d Of f s et ; 
n Rec o r d L e ng t h ; 
szReservedl 20] ; 



t ypedef struct { 

char s z Co I u mn Na me [ 1 1 ] 

char c h T y pe; 

long IFieldPointer; 

unsigned char byLength; 

unsigned char byDeci mal PI ace; 

char s z Res er ved[ 1 4] ; 
} COLUMNDEF; 



continues 
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Listing 12.2. continued 



i n t ma i n ( ) 
{ 

FILE * DBF i I e ; 

DB3HEADER db3Header ; 

struct _ DBRECORD { 

char sStatus[l]; /* Status does not count as a member */ 

char s Na me] 40 ] ; 

char sAddr 1[ 40] ; 

char sAddr 2[ 40] ; 

char s C i t y [ 2 0] ; 

char s St at e[ 2 ] ; 

char s Z i p [ 5 ] ; 

} Ou r Rec or d ; 

char * pOu r Rec or d ; 

COLUMNDEF Co I u mn De f [ 6 ] ; /* Six members in Our Record */ 

char s z B u f f e r [ 2 0 0 ] ; /* Work buffer */ 

char s z T i me [ 2 6 ] ; 

char szFi I eName[ 25] ; 

i nt i ; 

int nColumn Count = 0; 

i n t n Res u I t ; 

long ICurrentRecord = 0; 

double dSales = 0.0; /* Forces loading of floating-point support */ 

struct t m * Ne wTi me ; 

t i me _ t aClock; 

/* Step 1. Determine the layout of the columns (fields). In this 

* example, they are predefined. In other programs, you 
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* might determine the column layout by prompting the user 

* or by examining the user's data. 

*/ 

printf(" Please enter new database name: "); 

gets( szFi I elMame) ; 

DBFile = f o p e n ( s z F i I e Na me, "wb"); 

if (DBFile == NULL) 

{ 

f pr i ntf ( st der r , 

"ERROR: File ' %s ' couldn't be opened. \n", szFileName); 

exi t ( 4) ; 

} 

/* Step 2. Initialize and write the header record. 

*/ 

t i me ( &aCI oc k ) ; 

Ne wTi me = I o c a I t i me ( &a C I oc k ) ; 

memset ( &db3Header , 0, s i z eof ( d b 3 Hea de r ) ) ; 

/ * Make it d BASE I I I - compat i bl e */ 
db3Header. bfVersi on = 3 ; 

/* Make it a database with no memo fields */ 
db3Header . bf HasMemo = 0; 

/* Set the date to now, but UPDATE when closing */ 
/* because date may have changed */ 
db3Header. bYear = NewTi me- >t m_year ; 

db3 Header . bMont h = (unsigned c h a r ) ( Ne wT i me- >t m_ mo n + 1); 
db3Header. bDay = (unsigned char) NewTi me - > t m_ md a y ; 

/* No records in the database yet */ 
d b 3 Hea d e r . I N u mbe r Rec o r d s = 0; 
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Listing 12.2. continued 



/* File header, plus column headers, plus a byte for the carriage 
return */ 

db3Header . n F i r st Reco r dOf f set = si zeof ( DB3HEADER) + s i z e of ( Co I u mn Def ) 

+ 2; 

/* Make it the size of a record in the database */ 
db3Header . nRecor dLengt h = s i z eo f ( Ou r Rec o r d ) ; 

nResult = fwrite((char * ) &d b 3 H e a d e r , 
si zeof ( DB3HEADER) , 
1, 

DBFi I e) ; 

i f ( n Res u I t I = 1) 

{ 

f pr i nt f ( s t de r r , "ERROR: File ' %s ' , write error (Database \ 
header) . \ n", 

s z F i I e N a me ) ; 
f cl ose( DBFi I e) ; 
exi t ( 4) ; 

} 

/* Step 3. Initialize the column headers using the information from step 
1. */ 

mems et ( Co I u mn Def , 0, s i z eof ( Co I u mn Def ) ) ; 

/* Do the following for each column, either inline or using a loop */ 

s t r c py ( Co I u mn Def [ 0 ] . s z Co I u mn Na me , " Na me " ) ; 

Col umnDef [ 0] . chType = CHARACTER, Fl ELD; 

Co I u mn Def [ 0 ] . by L en g t h = s i z eof ( Ou r Rec or d . s Na me ) ; 

Col umnDef [ 0] . byDeci mal PI ace = 0; 



s t r c p y ( Co I u mn Def [ 1 ] . s z Co I u mn Na me , "Addressl") ; 

Col umnDef [ 1] . chType = CHARACTER, Fl ELD; 

Co I u mn Def [ 1 ] . by L en g t h = s i z eof ( Ou r Re c o r d . s Add r 1 ) 
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Co I u mn Def [ 1 ] . by Dec i ma I P I ac e = 0; 

strcpy( Col umnDef [ 2] . szCol umnName, "Address2") ; 
Col umnDef [ 2] . chType = CHARACTER, Fl ELD; 
Col umnDef [ 2] . byLengt h = s i z e of ( Ou r Rec o r d . s Ad d r 2 ) ; 
Co I u mn Def [ 2 ] . by Dec i ma I P I ac e = 0; 

s t r c py ( Co I u mn Def [ 3 ] . s z Co I u mn Name , " Ci t y " ) ; 

Col umnDef [ 3] . chType = CHARACTER, Fl ELD; 

Col umnDef [ 3] . byLengt h = si zeof ( Our Recor d. sCi t y) ; 

Co I u mn Def [ 3 ] . by Dec i ma I P I ac e = 0; 

st rcpy( Col u mn Def [ 4 ] . s z Co I u mn Na me , "State") ; 

Col umnDef [ 4] . chType = CHARACTER, Fl ELD; 

Col umnDef [ 4] . byLengt h = s i z e of ( Ou r Rec o r d . s S t a t e ) ; 

Co I u mn Def [ 4 ] . by Dec i ma I P I ac e = 0; 

st r c p y ( Col u mn Def [ 5 ] . s z Co I u mn Name , " Zi pc ode" ) ; 
Col umnDef [ 5] . chType = CHARACTER, Fl ELD; 
Col umnDef [ 5] . byLengt h = s i z eof ( Ou r Rec o r d . s Z i p ) ; 
Co I u mn Def [ 5 ] . by Dec i ma I P I ac e = 0; 

nResult = fwrite((char * ) C o I umnDef, 
s i z e of ( Co I u mn Def ) , 
1, 

DBF i I e) ; 

i f ( nResul t 1=1) 

{ 

f pr i ntf ( st der r , "ERROR: File ' %s ' , write error (Column \ 
h e a d e r s ) . \ n " , 

s z F i I e Na me ) ; 
f cl ose( DBF i I e) ; 
exi t ( 4) ; 

} 

/* Step 4. Write a carriage return (and a NULL) to meet dBASE standards 

*/ 



continues 
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Listing 12.2. continued 

n Res ill t = fwri te((char * ) "\ xOD\ 0" , 
si zeof ( char ) * 2, 
1, 

DBFi I e) ; 

i f ( n Res u I t I = 1) 

{ 

fpri ntf(stderr, "ERROR: File ' %s ' , write error (Column \ 
h e a d e r s ) . \ n " , 

s z F i I e N a me ) ; 
f cl o s e ( DBFi I e) ; 
exi t ( 4) ; 

} 

db3Header. nFi rstRecordOffset = ( i n t ) f t e I I ( DBF i I e ) ; 

/* Step 5. Get some records for the database. */ 

memset ( & Our Recor d, 0, s i z eof ( Ou r Rec o r d ) ) ; 

p r i n t f ( " E n t e r the n a me : (or no n a me to end)"); 
g et s ( szBuffer) ; 

s t r n c py ( Ou r Rec o r d. s Na me, szBuffer, s i z e of ( Ou r Re c o r d . s Na me ) ) ; 

whi I e ( s t r I en ( s z Buf f er ) > 0) 

{ 

OurRecord. sStatus[0] = USAB L E_ RECORD; 

pri ntf( "Enter address line 1 : " ) ; 
gets(szBuffer); 

s t r n c py ( Ou r Rec o r d . sAdd r 1 , szBuffer, s i z eof ( Ou r Rec o r d . s Ad d r 1 ) ) ; 

pri n t f ( " Enter address line 2:"); 
gets(szBuffer); 

s t r n c py ( Ou r Rec o r d . sAdd r 2 , szBuffer, s i z eof ( Ou r Rec o r d . s Ad d r 2 ) ) ; 
pri ntf( "Enter city:"); 
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get s ( sz Buf f e r ) ; 

strncpyf OurRecord. sCi ty, szBuffer, si zeof(OurRecord. sCi ty) ) ; 

pri ntf("Enter state (2 characters only):"); 
get s ( sz Buf f e r ) ; 

strncpyf OurRecord. sState, szBuffer, si zeof( OurRecord. sState) ) ; 

p r i n t f ( " E n t e r Z i p c o d e : " ) ; 
gets(szBuffer); 

strncpyf OurRecord. sZi p, szBuffer, s i z eo f ( Ou r Rec o r d . s Zi p ) ) ; 

/* dBASE records do not contain NULLs, but are padded with 

* blanks instead, so we convert the NULLs to spaces 

*/ 

pOurRecord = (char * ) &Ou r Re c o r d ; 

for ( i =0; i < s i z eof ( Ou r Rec o r d) ; i ++) 

{ 

if ( pOur Recor d[ i ] == ' \ 0' ) 
{ 

pOur Recor d[ i ] = ' ' ; 

} 

} 

nResult = fwriteffchar * ) &Ou r Re c o r d , 
si zeof ( Our Recor d) , 
1, 

DBF i I e ) ; 

if ( n Re s u I t ! = 1) 

{ 

fpri ntffstderr, "ERROR: File ' %s ' , write error (Column \ 
headers) . \ n " , 

s z F i I e Na me ) ; 
f cl ose( DBFi I e) ; 
exi t ( 4) ; 

} 

else 
{ 

continues 
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Listing 12.2. continued 

++db3Header . I Number Recor ds; 

} 

memset ( &Our Recor d, 0, sizeof(OurRecord)); 

pri ntf( "Enter the n a me : (or no n a me to end)"); 
gets(szBuffer); 

st rncpy( Our Recor d. sName, szBuffer, si zeof(OurRecord. sName) ) ; 



/* Step 6. Update the file header with the current time and 
* the number of records. 

*/ 

t i me ( &aCI o c k ) ; 

NewT i me = I o c a I t i me ( &a CI o c k ) ; 

/ * Set the date to now */ 
db3Header . bYear = N e wT i me - >t m_ y e a r ; 

db3Header. bMonth = (unsigned c ha r ) ( NewTi me- >t m_ mon + 1); 
db3Header . b Da y = (unsigned char) N e wT i me - >t m_ md a y ; 

/* The number of records is already set */ 

nResult = f seek( DBFi I e, (long)0, SEEKSET) ; 

if ( n Res u I t 1=0) 

{ 

f pr i nt f ( s t de r r , "ERROR: File ' %s ' , seek error (rewrite of \ 
header) . \ n " , 

s z F i I e N a me ) ; 
f cl ose( DBFi I e) ; 
exi t ( 4) ; 

} 

nResult = fwrite((char * ) &d b3 He a de r , 
si zeof ( DB3HEADER) , 
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i, 

DBF i I e) ; 

i f ( n Re s u I t 1=1) 
{ 

f pr i ntf ( st der r , "ERROR: File ' %s ' , write error (Database header \ 
r ewr i t e) . \ n" , 

s z F i I e Na me ) ; 
f cl ose( DBF i I e) ; 
exi t ( 4) ; 

} 

/* Finished. Close the file and end the program. 



f c I os e ( DBF i I e) ; 
r et u r n ( 0 ) ; 



Your program that creates a dBASE file must do the foil owing, in order: 

1. Determine the record layout. This may have been already defined by the 
application's requirements, or you may be using information supplied by the 
user. Each field must have a type and a length. 

2. Initialize and writeadBASE file header (our db3 read structure). You must 
initialize the record size(sum of fields plus the leading record deleted byte), the 
pointer to the first record, usually the byte after the end of header byte (see 
step 4), the date, and the time. 

3. I nitialize and write thefidd headers (our col umnde f structure). Besureyou 
specify the field's name, length, and type. 

4. W rite the end of the header byte (OxOD ); following the header byte with a 
null byte (0x00) is optional. 

5. Write the records placed in the file at creation time. Be sure the deleted flag is 
set to blank so that the initial records are not deleted. 
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6. Seek to the beginning of the file and reset the file header's number of records 
count, date, and time. (Thedateand time are reset because they have changed 
si nee they were last written.) Rewrite the file header. 

E ach of th ese si x steps were f ol I owed in D BW RIT E.C and areindi cated by com men ts 
in the program. 

Updating dBASE and dBASE-Compatible Files 

When you updatea dBASE file, I suggest that you updatea copy of the original file. 
If you update the original file, you risk damaging the original file if your program 
crashes. I never work on theonlycopy of afile. Instead, I copy the original .DBF file 
to a .BAK file or a temporary work file. 

Thestepsfor updating a dBASE filefollow: 

1. Read thefile header and thecolumn (fidd) header records. 

2. Read the file's data records if necessary. Append to the file any new records 
that the user creates. I f the user is deleting a record, mark it with the* ddete 
flag in the first column (theddeted fidd) of the data record. M odify records as 
necessary. W hen modifying a record, many programs mark the original record 
asddeted, then make the changed record a new record. Although this tech- 
nique is acceptable, the database file may grow excessivdy if many records are 
changed. 

3. Write the updated file header record with a new date and record count. 

U sing a dBASE-compatible file structure increases your program's flexibility 
because the user can use other utilities (including a database program) to manipulate 
the data files. 



Summary 

I n thischapter, you learned about interfacing C with database programs and with files 
created by d BASE -com pati bl e programs. 

• Database programs are one of the most common computer applications. 

• Themost common database file format isthedBASE III format. It is simple 
and easy to use. 
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A dBASE III .DBF file can be read using two structures, as shown in the 
chapter. 

A dBASE III file can be created using simple C functions. 

A .DBF filecan contain deleted records. It is possible to write a program that 
recreates the database and undeletes the deleted records— if the database has 
not been packed and the space that the deleted records occupied has not been 
lost. 



■1 
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H eader files are a feature of the C language that helps the programmer write better 
programs. Therearetwotypesof header files: thefiles that theprogrammer writes and 
th e f i I es th at com e wi th you r com pi I er. T h i s ch apter covers f i f teen stan dard C h eader 
files. First, though, the chapter reviews the usage of function prototypes and how to 
make your prototypes more effective. 



The terms header fileand include file are commonly used interchangeably. 
T here are no differences between the two— header files are include files. 



Function Prototypes 

Oneof themostvaluableimprovementstoC istheaddition of function prototypes. 
A function prototype specifies the order and types of arguments that will be passed to 
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a function. It specifies also the type of the function's return value, if the function 
returns a value. In early versions of C, the compiler would accept any arguments to a 
function. 

Suppose that a function called Mui t fi oat ( ) accepts two float arguments and 
returns the product of thetwo arguments asat i oat . Using an earlyversion of C that 
doesnothavefunction prototypes, you could pass two integerstOMui t fi oat ( ) .These 
arguments would be passed unchanged, and mu i t f i o a t ( ) — unaware of the wrong 
argument types— would return a bogus value or signal a floating-point error. 

A function prototype consists of three major parts: 

• The return value. If the function returns nothing, the prototype should have a 
return type of voi <j . 

• The function's name. I recommend that you use mixed case and no under- 
scores. Underscores can be a problem with linkers that allow only six signifi- 
cant characters. 

• The function's parameters. Beexplicit about size and type when possible. If 
you can, include the variablename that will beused by thefunction because 
the name implies what the argument does. 

Thefunction prototype is the declaration of thefunction. Thefunction itself is 
defined (and has a body) later in the program or in a different source file. 

Following is a function prototype for a function that compares two strings: 

i nt 0 u r S t r C mp (void far *, void far *); 

In this function prototype, a function returns an integer. The size of this integer is 
unimportant and therefore undefined— it could beshor t or i ong, depending on the 
compiler'sdefault integer size. If thesizeof thereturned valueis important, you must 
specify the size, our st rcmpi ) returnsa valuethat isonly lessthan zero, zero, or greater 
than zero. 

Both oftheparameterspassed to thefunction aredefinedaspointerstotypevoi d . 
H ere, thevoi d typemeansthepointershaveno specific type, and any pointer typecan 
be passed. If your function expects only a character string pointer, specify thisin your 
function prototype. If the arguments will not be modified when passing pointers, 
specify this also using thee ons t keyword. 
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Because ourstrcmpi ) only compares strings, the prototype could be more 
specific. Rewriting the function prototype for ou r s t r c mp ( ) results in the following: 

short i nt OurStrCmp(const char far *, const char far *); 

Now thefunction prototype is more complete. H owever, let'sadd thevariable 
names to make it more readable: 

short i nt Ou r St r Cmp( c o n s t char far * szStringA, 
const char far * szStringB); 

This prototype is more detailed and allows the compiler to check the types of the 
arguments passed to thefunction. In addition, when thefunction is created, the 
prototype is used to check whether the function has been properly declared. 

If you writeyour prototypes liketheonepresented here, the easiest way to write 
the function for that prototype is to start with the prototype, delete the ending 
semicolon, and add the function's opening and closing braces. Although many 
prototypes are written on oneline, a function's declaration is commonly written with 
each argument on a new line, as follows: 

short i nt Ou r St r C mp ( /* Returns the result of the compare */ 

const char far * szStringA, /* The first string to compare */ 
const char far * szStringB) /* The second string to compare */ 

{ 

/ * The body of the function */ 
} / * end: Our St r Cmp( ) */ 

This function declaration fully documents the return value and the parameters. 

When you createa header file, providefor the possibility that the header file is 
included more than once. A typical way to do this is to create an identifier; if the 
identifier exists, the header file has already been included. This could be coded as 
follows: 

#ifndef _ MY HEADE R 
tdefine _MYHEADER 

/* Other lines in this header file */ 
#endi f / * _ MY HEADE R */ 

The.MYHEADER identifier must remain unique. This technique prevents errors from 
symbols defined more than once. 
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The AN SIC Header Files 

ANSI C compilerscontain a number of standard header files. These files are used for 
specific purposes— try not to include header files if you will not be using their 
functionality. For example, if your program does not have any time-based functions, 
including m me. h will not improve your program but will slow the compiler. 

Table 13.1 lists some common identifiers. The table includes both defined 
identifiers and those that are integral parts of theC language. 

Table 13.1. Typical header file identifiers. 
Identifier Description 

si ze t An identifier that is guaranteed to hold the size of any 

definable data object. This identifier is usually defined as 

type unsigned int. 

far W ith segmented (PC 80x86) architecture, a 32-bit pointer. 

U sually consists of a segment (or selector) and an offset. 

near With segmented (PC 80x86) architecture, a 16-bit pointer. 

U sually consists of an offset, without any segment (or 
selector) information. The object being identified isin the 
default segment. 

fi le Thefilenameof thecurrent file(and header files that have 

been included). 

line Thecurrent line number of the current file. Each included 

header file has its own number. 

const A modifier that tells the compiler that the variable should be 

treated as a constant and should not be modified. 

volatile A modifier that tdlsthecompiler that the variable may be 
changed in a way that the compiler cannot detect. Examples 
of undetectable changes are when the variable is modified by 
an interrupt handler or by a function that uses set j mp( ) . 
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Therest of thischapter describesthestandard C header files. H eaderfilesspecific 
to particular C compilers are not included in thediscussion. To learn about compiler- 
specific header files, refer to your compiler's documentation and look at the files 
themsdves. 

Your compiler may not contain all the header files described in thischapter. If 
that isthecase,thecontentsoftheheaderfile(or files) areprobably included in another 
header file. A likdy choice is the stdi i b. h file, which often serves as a catchall. 



Theasser t . h header fileisused for thea s s e r t ( ) macro. N otethatassert ( ) isalways 
implemented as a macro and is never directly implemented as a function. 

You can test a condition with theasser t( ) macro. I f thecondition testsasTRUE , 
nothing happens. If thecondition tests as f a l s e , thefollowing message is printed to 

s t d e r r : 

Assertion failed: condition, filename, linenumber 

Thecondi ti on is printed as a text string, along with the source file name and the 
current linenumber in thecurrent file. After themessageisprinted, theprogram calls 
aborto to end the program— a failed a s s e r t ( ) definitely ends your program! 

To turn off the effect of the assert o macro, you must define the ndebug 
identifier. W hen this identifier is defined, a s s e r t ( ) evaluates as ( ( v o i d ) o ) , which is 
effectively nothing. 

The typical definition of theasser t( ) macro is 

#define asser t ( exp) ( ( exp) ? (void) 0 : \ 
_asser t ( #exp, _ _ F I L E _ _, _ LI N E _ J ) 

If the expression evaluates to false, thecondition, filename and linenumber in the 
asserto macro are passed to a f u n cti on . I f th e con d i ti on eval u ates to t r u e , th e macro 
evaluates to (( voi d) o) . 

Theassert ( ) macro is a valuable tool when you are debugging your program, 
butyou must remember to defineNDEBUG when creating the production version of the 
program. 
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Thectype.h File(ANSI) 

Thee type, h header file contains the character conversion functionsthat work with a 
singlecharacter. For conversion functionsthatusestrings, seethes t r i ng. h headerfile. 
A character can be classified as any one of the types shown in Table 13.2. 



T able 13. 2. C ommon character type identifiers not part of the 
ANSI standard. 



Identifier 


Description 


_ UP P E R 


An uppercase letter 


_ LOWER 


A lowercase letter 


_ D 1 G 1 T 


A digit (0-9) 


SPACE 


A tab, a carriage return, a newline, a vertical tab, or a form 




feed 


PUNCT 


A punctuation character 


_C0NTR0L 


A control character 


BLANK 


A space character 


HEX 


A hexadecimal digit (0-9, a-f, A-F) 



Thefollowing functions are defined in thee t y p e . h headerfile. Although these 
functionsaredefined with a parameter typeofi nt , they aretypically passed a parameter 



of char . The compiler performs the necessary conversion. 



sal p h a ( ) 


ReturnsTRUE 


if the character is alphabetic 


supper ( ) 


ReturnsTRUE 


if the character is uppercase 


si ower ( ) 


ReturnsTRUE 


if the character is lowercase 


sdi gi t ( ) 


ReturnsTRUE 


if the character is a numeric digit 


sxdi gi t ( ) 


ReturnsTRUE 


if the character is a hexadecimal digit 


sspace( ) 


ReturnsTRUE 


if the character is a whitespace character 


s pu nc t ( ) 


ReturnsTRUE 


if the character is a punctuation character 
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isainumo ReturnsTRUE if the character is alphabetic or numeric 

isprintu ReturnsTRUE if the character is a printable character 

isgrapho ReturnsTRUE if the character is a nonspace printable 
character 

iscntrio ReturnsTRUE if the character is a control character 

toupperi i Converts the character to uppercase 

t o i o we r ( i C onverts the character to lowercase 

t o i o we r ( i C onverts the character to lowercase 

_ t o u p pe r ( i Converts the character to uppercase 



M anyofthesefunctionsarealsodefinedasmacros. SeeTablel3.3.Thesemacros 
areusedunlesstheyareundefinedusingthetundef statement, which mustbeincluded 
after thectype. h header file is included. 



Table 13.3. Character classification macros. 



Macro 


Definition 






i sal pha( _c) 


( (.ctype+l) [ _c] 


& 


(_ UP P E R| _ LOWER) ) 


i supper ( _c) 


( (.ctype+1) [ _c] 


& 


.UPPER ) 


i si o we r ( _ c ) 


( (.ctype+l) [ _c] 


& 


_ LOWER ) 


i sdi gi t ( _c) 


( (.ctype+1) [ _c] 


& 


_ D 1 G 1 T ) 


i s x d i g i t ( _c ) 


l(.ctype+l)[_c] 


& 


_ H E X ) 


i sspace( _c) 


( (.ctype+1) [ _c] 


& 


_SPACE ) 


i spunct ( _c) 


( (.ctype+1) [ _c] 


& 


_ P UNCT ) 


i sal num( _c) 


( (.ctype+1) [ _c] 


& 


( _ UP P E R _ L OWE R _ Dl Gl T ) ) 


i s pr i n t ( _ c ) 


( (.ctype+1) [ _c] 
( _ BLANK _ P U N CT 


& 

_ UP PE R _ L OWE R | _ D 1 GIT) ) 


i sgr a p h ( _c) 


( (_ct ype+1) [ _c] 
( _ P U NCT _UPPER 


& 

_ L OWE R _ Dl Gl T ) ) 


i s c n t r 1 ( _ c ) 


( (.ctype+1) [ _c] 


& 


.CONTROL ) 



continues 
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Table 13.3. continued 



M aero 


D efinition 

mm \*l 1 1 II hi VI 1 






t o u d d e r ( c ) 


f ( i 5 1 o we r ( r ) ) 


? t o u n n p r ( r) 


( c ) ) 


t o 1 o wer ( _ c ) 


(( i s upper ( _c ) ) 


? _ t o 1 owe r ( _c ) : 


(_c) ) 


_ t o 1 o we r ( _ c ) 


(Lc)-'A' +'a' ! 






_t oupper ( _c) 


((_c)-' a 1 +' A 1 ; 






__i sasci i (_c) 


( ( unsi gned) ( _c; 


< 0x80 ) 




toasci i ( _c) 


((_c) & Ox 7f ) 







T he character classification macros reference an array of bytes called _ct ype .The 
bi ts i n th i s array are set based on th e ch aracter's classification. T his all ows a fast test of 
a character's attributes in a macro. 

Both the t oupper ( i and toi o wer o functions return the correctly converted 
character or the supplied character if there is no conversion. It is no longer necessary 
to check whether the character is uppercase or lowercase first. 

The errno.h File (ANSI) 

T he e r r n o . h header file has identifiers for the error codes returned by the e r r n o ( ) 
function. C compilers may define different values for each identifier, so you should 
never hard code an integer constant— use the identifier instead. 

Theer r not ) function isgenerally coded asa function, then defined to appear as 
a variable called e r r n o . T able 13.4 lists the common values for e r r n o . 

Table 13.4. Typical errno values. 
Error code Description 

e2big The argument list is too long. 

eacces You cannot access the file, probably becausethefileis not 

compatible with your request or thefilehasan attribute 
(such as read only) that is incompatible with your request. 
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Error code Description 

eagai n You cannot create any more child processes. 

ebadf The specified file number is invalid (probably not a 

currently opened file), or thefile is opened in a mode 
incompatible with the requested action. 

e deadlock T he resource could not be locked (after a preset number of 
tries), and a resource deadlock would occur. 

e dom The argument to a math function is not in the domain of 

thefunction. 

eexi st Thefilethat isto becreated already exists. 

ei nval T he specified argument is invalid. 

emfile Too many files are open. 

e noe nt T he file or directory cannot be found. 

enoexec Thefilethat was to be executed was not an executable file. 

e nome m T here is not enough RAM . 

enospc T he disk drive isfull. 

e range The argument to a math function was too large, resulting in 

a partial or total loss of significance. 

exdev An attempt was made to rename (using rename! ) ) afiletoa 

new directory on a different drive. 



Otherer mo valuesarespecifictotheenvironmentorcompiler.Theuseofer mo 
is generally defined in a function's error conditions. For example, the description for 
thereadi ) function includes information that e r r no may be set to ebadf if a bad file 
handle is encountered. 

Include <i o. h>, <er r no. h> 

Syntax int read( int handle, void * buffer, unsigned int 

count ) ; 
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Returns 



T he number of bytes read or 0 at the end-of-file if the 
function was successful. Returns -1 if the function was 
not successful. 



er r n o : EBADF 



Thef loath File (ANSI) 



The floating-point header file, float, h , includes important information about the 
implementation's floating-point capabilities. This header file was discussed in 
Chapter 2, "DataTypes, Constants, Variables, and Arrays" 

Thef i oat . h header file is important to any program that uses floating-point 

math. 

As the following list shows, most of thef i oat. h header file deals with various 
constants. You can use these constants if necessary. For example, I use the f lt_ mi n 
value to indicate a value that is missing (which is different from a zero valuein my 
program). 

dbl di g For a datatypeof f i oat , thenumber of 



decimal digits of precision 



DBL EPSI L ON 



For a datatypeof f i oat , the smallest value 
such that l. o + dbl epsi lon i = i. o 



DBL MANT DI G 



For a data type of d o u b i e, thenumber of bits 
in the mantissa 



DBL MAX 



For a data type of doubi e, the maximum value 



DBL MAX 10 EXP 



For a data type of doubi e, the maximum 
decimal exponent 



DBL MAX EXP 



For a data type of doubi e, the maximum 
binary exponent 



DBL Ml N 



For a data type of doubi e, the minimum 
positive value 



DBL Ml N 10 EXP 



For a data type of doubi e, the minimum 
decimal exponent 
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dbl mi n exp F or a data type of d o u b i e, theminimum 

binary exponent 

f l t _ d i g For a data type of f i oat , thenumber of 

decimal digits of precision 

flt epsi lon For a data type of f i oat , the smallest value 

such thati. o + flt_epsi lon i = 1. o 

flt mantdi g For a data type of f i oat , thenumber of bits in 

the mantissa 

flt max For a data type of f i oat , the maximum value 

flt max 10 exp For a data type of f i oat , themaximum 

decimal exponent 

flt max exp For a data type of f i oat , themaximum binary 

exponent 

flt mi n For a data type of f i oat , theminimum 

positive value 

flt mi n 10 exp For a data type of f i oat , theminimum 

decimal exponent 

flt mi n exp For a data type of f i oat , theminimum binary 

exponent 

flt radi x For a data type of f i oat , the exponent radix 

flt rounds For a data type of f i oat , addition rounding 

ldbldig For a data type of i ong do u bi e, thenumber of 

decimal digits of precision 

ldblepsi lon F or a data type of i ong d o u b i e , the smallest 

value such that l. o + ldbl_epsi lon != 1.0 

ldblmantdi g F or a data type of i ong do u bi e, thenumber of 

bits in the mantissa 

ldbl max For a data type of i ong do u bi e, themaximum 

value 

ldblmaxioexp F or a data type of i ong do u bi e, themaximum 

decimal exponent 
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ldblmaxexp For a data type of i o n g do u bi e, the maximum 

binary exponent 

ldbl _ mi n For a data type of i ong doubi e, theminimum 

positive value 

ldblmi nioexp For a data type of i o n g doubi e, theminimum 

decimal exponent 

ldbl mi n exp For a data type of i o n g doubi e, theminimum 

binary exponent 



The io.h File 



Thei o. h headerfilesupplementsthestdi o. h headerfileof AN SI C.Thefileasshown 
in thisbook, isused withvariousM icrosoft versions of C. Thei o. h headerfilecontains 
various low-level I/O function prototypes. 



Thelimits.h File (ANSI) 



All parts of the C language contain limits. M any of the limits that apply to floating- 
point math are i nth en oat. h header file. T heinteger limitsarein thei i mi ts. h header 
file and are shown in thefollowing list: 

char bit Thenumber of bitsin achar 

schar mi n Theminimum signed char value 

schar max The maximum signed char value 

uchar max The maximum unsigned char value 

char min and schar min T he minimum c h a r value 

charmax and scharmax The maximum char value 

mb len max Themaximum number of bytes in a 

multibytechar 

shrt mi n Theminimum (signed) short value 
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Ul NT MAX 



SHRT MAX 



US HRT MAX 



ULONG MAX 



LONG MAX 



I NT MAX 



LONG Ml N 



I NT Ml N 



The maximum (signed) short value 
The maximum unsigned short value 
Theminimum (signed) int value 
Themaximum (signed) int value 
The maximum unsigned int value 
Theminimum (signed) long value 
Themaximum (signed) long value 
Themaximum unsigned long value 



R ath er th an h ard cod e n u m eri c val u es f or th ese val u es, al ways u se th e i d en t i f i ers. 



Therearemorewaystotell thetimethan therearehoursinaday. M anycountrieshave 
a special way of writing thetimeand date, and sometimes onecountry has more than 
oneway to specify the time or date. 

Thei oca i e. h headerfiledefineshowtimeand datesareformatted forthecurrent 
country. You can setthelocaleby callingtheC set i ocai e( ) function, with oneof the 
parameters in Table 13.5 as the first parameter. The second parameter is either the 
character string " c (for U nited Statesdefaults) or " ■ forthenativecountry'sdefaults. 
Any other string for the second parameter depends on the implementation of the 
compiler. 

Table 13.5. Locale identifiers used with the Iconv structure. 
Identifier Description 

lc all Sets all categories. 

lc collate Sets the collate order. U sed by s t r c o 1 1 ( ) and strxf rm( ) 

lc ctype Sets the character set queries for c t y p e . h 

lc monetary Sets the display format for currency. NoC functions use this 




information. 



continues 
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Table 13.5. continued 


Identifier 


Description 


LC_ NUME Rl C 


Sets the display format for numbers. Used by pri ntf ( ) and 




scant o type functions. 


L C _ T 1 ME 


Sets the display format for the time. This affects s t r f t i me ( ) , 




ct i me( ) , and a s c t i me ( ) . 



Thei ocai econvi ) function returns a pointer to the internal i conv structure, 
which containstheformatting information. T heformat and contentsof i conv depend 
on the compiler, and as such are not documented here. 

Although you can get a pointer to the i conv structure, you must use the 
set i ocai e( ) function to modify it rather than modify it directly. This limits your 
directuseofthestructuretoreadonly.Savetheinformation pointedtobyi ocai econvi ) 
in a buffer in your program because the structure pointed to by i ocai econvi ) may 
change or move. 

The malloc.h File 

Your system may havea header file called ma 1 1 oc. n. This header supplements the 
stdiib.h header file that is part of AN SI C. The ma 1 1 oc. h header file contains 
functions, identifiers, and other things that deal with memory allocation. 

The math.h File (ANSI) 

Themat h. h header fi ledefi nes prototypesfor thevariousf loati ng-poi nt functions. T he 
mat h. h file and theer r no. h file are often included with then oat . n header file. 
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The memory.h File 

Theme mo r y . h header filecontainsfunction prototypesforthememoryfunctionsand 
buffer manipulation functions. M anyAN SI C compilersincludethesefunctionsin the 
stri ng. h header file. SeeTablel3.6. 

Table 13.6. Memory functions. 



Function Description 



me mc h r ( ) 


Returns a pointer to the first byte in a block matching the 




specified character 


me mc mp ( ) 


Compares two blocks of memory, returning any differences 


me mc p y ( ) 


C opies two nonoverlapping blocks of memory 


me mmo v e ( ) 


Copies two blocks of memory, which mayor may not 




overlap 


me ms e t ( ) 


Fillsa block of memory with the specified byte 



The memory functions are used in much thesameway as thestring functions. 
M emory functions, however, work with a specific length; string functions expect a 
terminating null to marktheend of thestring. 



The search. h File 

T hes e a r c h . h header filecontainsfunction prototypesfor thesearch and sort routines. 
Many AN SI C compilers contain these functions in the s t d i i b . h header file. The 
search function, bsearcho, performs a binary search. The sort function, qsorto, 
performs a quick sort. Both functions require a user-written compare function. 
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The setjmp.h File (ANSI) 

Theset j mpo and i ongj mp( ) functions are defined in the s e t j mp. h header file. The 
ANSI C standard defines set j mp( i as a macro. H owever, some compiler producers 
have written set j mp( i as a function. 

T he signal, h File (AN SI) 

ANSI C uses a signal to tell the program that an error has occurred. The si gnai . h 
header file defines the conditions that are trapped and optionally passed to the 
program. SeeTablel3.7. 



Table 13.7. Signal values. 


Value 


Description 


SI Gl NT 


An interrupt, such asaCtrl-C keypress. Required by AN SI. 


SI Gl LL 


An illegal instruction or an anomaly in the program's 




execution that is usually caused by corrupted memory. 




Required by AN SI. 


SI GFPE 


A floating-point error or another math error exception. 




Required by AN SI. 


SI GSEGV 


An attempt to access memory was made that the program 




does not allow. Required by AN SI. 


SI GTERM 


T he program was requested to end (probably caused by the 




operating system shutting down). Required by AN SI. 


SI GBREAK 


A Ctrl-Break sequence. 


SI GABRT 


Abnormal termination, perhaps triggered with a call to 




abort o . Required by AN SI. 



Thetwo functions that deal with signaling arer a i sen , which triggers a signal 
condition, and si gnai ( ) , which sets up the handler for the error condition. 
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Thestdarg.h File(ANSI) 

The stdarg. h header file has been designed to replace the v a r ar gs. h header file. 
Generally, you cannot mix these two header files in the same source file. 

An important part of C programming isthecapabilityto useavariablenumber 
of arguments. Just think of how pri ntfo or scant o would work without this 
capability. 

If yourprogram uses thestdarg.h header file, a function with a variable number 
of arguments must have at least one fixed (always present) argument. This fixed 
argument is passed to the va. start o routine to enable access to the variable 
arguments. 

The program in Listing 13.1, VARGS.C, shows two ways to use a variable 
number of arguments. T heou r e r r o r s ( ) function shows theuseof vf p r i nt f ( ) as well. 
Because the vf pr i ntf ( ) is new, many programmers do not fully understand it yet. 

Listing 13.1. VARGS.C 

/* VARGS, written 1 9 9 2 by Peter D. Hipson */ 
/* This program demonstrates stdarg. h */ 

# i n c I u d e <l i mi t s . h> 

# i n c I u d e <s t d a r g . h > 

# i n c I u d e <st di o. h> 

# i n c I u d e <s t d I i b . h > 

#def i ne TRUE 1 
#define FALSE ( ! TRUE) 

i n t Ad d L i s t ( i n t n F i r s t , . . . ) ; 

i nt Ou r E r r o r s ( c h a r * Out put For mat , ...); 

void ma i n ( ) 
{ 

i nt nSum; 

continues 
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Listing 13.1. continued 

nSum = AddLi st ( 10, 2 0, 3 0, 40, 5 0, 6 0, 7 0, 80, 9 0, I N T _ Ml N ) ; 
( v o i d ) 0 u r E r r o r s ( " %s - %d, %s\n M , "First", nSum, "Second"); 

} 

int AddLi s t ( 
i nt n F i r s t , 
. . . ) 

{ 

int nReturnVal ue = n F i r s t ; 
int nThi sVal ue; 

v a _ I i st Arguments; 

va_start(Arguments, nFirst); 

whi I e( ( nThi sVal ue = v a_a r g ( Ar g u men t s , int)) != I N T _ M I N ) 

{ 

nRet ur nVal ue += nThi sVal ue; 

} 

va end(Arguments) ; 
r et u r n ( n Ret u r n Va I u e ) ; 

} 

int Ou r E r r o r s ( 

char * 0 u t p u t F o r ma t , 
. . . ) 

{ 

v a _ I i s t Arguments; 

va_start(Arguments, Output For mat ) ; 
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vfpri ntf(stderr, OutputFormat, Arguments); 



va_end(Arguments); 



r e t u r n ( 0 ) ; 



The stddef.h File (ANSI ) 



Thestddef . h header fileisoneofthemoreimportant header filesfortheC compiler. 
T hisheaderfilecontainsmanycommon constants, identifiers, types, and variables, for 
example,NULL and of f setoff ) .TheNun identifier isdefined aszeroor asapointerthat 
isguaranteed to point to nothing. Theof f set of ( ) macro determines the offset from 
the beginning of a structure to a given member. M ost nontrivial programs should 
includes t d d ef . h. 



M ost of the higher levd I/O functionsarein thestdi o. h header file. Thisfile is used 
in most (if not all) programs, because a program without I/O is rather uncommuni- 
cative! 

Oneitem defined in st di o. n isthestructurethattheFi le* typepointsto. N ote, 
however, that you should never modify this structure's members. 

Also defined in st di o. n aretheconstantsthatf seeki ) uses, i ncluding seek cur 
(the current file position), seekend (theendof thefile), and seek set (thebeginning 
of the file). 

The stdi o. h header file also contains the prototypes for the various I/O 
functions and the standard file identifiers— stdi n, stdout, stderr, stdaux, and 

st dpr n . 
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The stdlib.h File (ANSI) 

Thestdi i b. h headerfilecontainsthedefinitionsand declarationsfor commonly used 
libraryfunctions. Theselibraryfunctionsareusuallyfound in thes t d i i b. h header file 
becausetheydo not fitdsewhereor cannot beplaced in other header files for technical 
reasons. This section describes some of thefunctionsin thestdi i b. h header file. 



String Conversion 

The string conversion functions convert strings to their numeric equivalent. The 
conversion process is performed in accordance with the locale settings, so that the 
thousands separator (a comma in the U nited States) may be recognized. The three 
AN SI functions for string conversion arestrt odd , st rt oi ( ) , and st rt oui ( ) . 



Memory Allocation 

If acompiler doesnothaveaseparatememory allocation header file(such as ma 1 1 oc. h), 
the memory allocation functions are defined in stdi i b. h. 



Random Numbers 

TheC random numberfunctioniscalledr and ( ) .Therandomnumbersmaybeseeded 
usingsr and( ) . T hesequenceof random numbers repeats, however, if s r a n d ( ) receives 
the same seed each time. A common trick is to seed the random numbers with the 
current time or the elapsed time between two (or more) keystrokes. 



Communications with the Operating System 

You can issueoperatingsystem commandswith thes y s t e m( ) function. T hisfunction's 
behavior is not defined by AN SI C, with two exceptions. If thesyst em( ) function is 
called with aNun parameter, it returnsTRUE if a command interpreter is present. If the 
system! i parameter is called with null andsignaio returns zero, you cannot issue 
commands to the operating system. 
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You can usetheat exi t ( ) function to tell theoperating system which functions 
should be called when the program ends. Although you can include functions, they 
cannot be removed after installation. 

You can useabor t ( i to end your program. Regardlessof theuseof thesi gabort 
signal error handler, abort ( ) will not return to the caller. 



Thebsearchi i function is often defined in stdi i b. h . WhybsearcM ) is defined here 
and qs or to is not is beyond me. 



ANSI C has two integer math functions. These functions enable you to divide two 
integer values, and provide both a quotient and a remainder in onecall. As well, these 
functions produce more predictable results than the division operator. 



BecauseANSI C supportsmultibytecharactersets(usefulforlanguagesthatdonotuse 
th e rom an character set) , th ere are f u n cti on s to su pport ch aracter sets th at h ave more 
than 256 characters. These characters are represented with a two- byte sequence, and 
their values depend on both the compiler and the language. You must read your 
compiler'sdocumentation to determinewhich functionsareprovided and how to use 
them. 



Thevariousstring manipulation functionsaredefined in thest r i ng. h headerfile. This 
file also contains various memory functions (such as the ones found in thememory. h 
headerfile). 



Search Functions 



Integer Math 



M ultibyte C haracters 
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The time-h File (ANSI) 

The time functions are in the t i me. h header file. ANSI C added the s t r f ti men 
function to the C language, which helps you format a time string. 

The varargs.h File 

In mostC compilers, thevarargs. h header file has been replaced with thestdarg. h 
header file. You usually cannot mix these two header files in the same source file. 



Summary 

In this chapter, you learned about theAN SI standard header files. 

• Although there are standards for header files, most compilers add header files 
that offer additional functionality (such as graphics) or split the functionality 
of existing AN SI header files into several new files (such asM icrosoft'suseof 
the memory, h header file). 

• Thevarargs. h and thestdarg. h filesboth definethe passing of a variable 
number of arguments to a function. In general, thestdarg. h header file is 
considered theAN SI standard way to pass a variable number of arguments. 
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Part IV 

c 

Documenting the 
Differences 



ANSIC'sLibrary 
unctions 

This chapter presents the AN SI C standard functions. I have not included functions 
that are not ANSI — there are several hundred additional non-ANSI functions that 
vary both in function and implementation between different compilers. Forthenon- 
ANSI functions, it is preferable to use the documentation that is supplied with the 
compiler because there may be differences between different implementations of a 
non-AN SI function that you would not expect. 
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Functions 



The AN SI C libarary functions are presented below in alphabetical order. 

abort!) 

Header: process.h & stdlib.h 

Syntax: void abort(voi d) ; 

Description: Aborts (ends) the current program or process. 

Parameters: None. 

Returns: Does not return to caller. 

Example: if (nDis aster) 

{ 

abort () ; 
} 

Note: Generally, useaborto only if recovery is not possible. Open files 

will probably be lost and any work entered by the user and not 
saved cannot be recovered. 



abs() 

H eader: 

Syntax: 

Description: 

Parameters: 

Returns: 

Example: 



math.h & stdlib.h 

i n t a bs ( i n t n V a I u e ) ; 

Returns the absolute value of the provided parameter, 
nvai ue — A signed integer whose absolute value is desired. 
Returns the absolute value of the provided parameter. 

pri ntf ( " a b s ( - 20) = %d\n", abs ( - 20) ) ; 
/ * Wi I I print: a b s ( - 2 0 ) = 2 0 * / 
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acos() 

Header: math.h 

Syntax: double acos( double dValue); 

Description: Provides the principal arc cosine of d va i ue. 
Parameters: dvai ue — Type double, ranging -1 to 1. 
Returns: Arc cosine, a value between zero and 3.1415926. 

Example: dArcCos = acos(0. 4) ; 

/* dArcCos wi I I be 1. 0 4 7 */ 

Note: Setsermo to e dom if the parameter passed is outside the allowed 

range. 



asctime() 

H eader: 
Syntax: 

Description: 

Parameters: 
Returns: 

Example: 



Note: 



tirneh 

char * ascti me(const struct t m * 
TimePointer); 

Converts time as contained in parameter n mePoi nter to a 
character string. The string's format follows the example: 

We d j u n 2 4 2 2:2 1:0 0 1 9 9 2 \ n \ 0 . 

A pointer to a properly initialized time structure. 

A character pointer to astring. You should copy this string to your 
program's own memory if you wish to save it. 

struct t m t mT i me ; 
t i me _ t I T i me ; 

t i me ( & I T i me ) ; 

t mT i me = I o c a I t i me ( &l t i me) ; 

p r i n t f ( " T i me : ' %s ' " , a s c t i me ( &t mT i me ) ; 

I nitialize thetimestructure(t m in theexample) using t i me( ) and 

I o c a I t i me ( ) . 
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asin() 

H eader: 

Syntax: 

Description: 

Parameters: 

Returns: 

Example: 



math.h 

double asi n( doubl e dVal ue) ; 

R etu rn s the arcsi n e of param eter <j v a i u e . 

dvai ue — Which must bein therangeof -1 and 1. 

Thearcsineof dvai ue. 

d Ar c Si ne = as i n ( 0. 5 ) ; 
/* dArcSi ne wi I I be 0. 5 2 3 6 */ 



assert!) 

H eader: assert, h 

Syntax: void assertf unsi gned nConditional); 

Description: Theasserto macro prints a message. 

Parameters: ncondi t i onai —A conditional expression, such asi ncount < o) . 

Returns: No return value. 

Example: assert(nCount < 0); 

Note: If the conditional expression evaluates to 0, then a message 

containing the conditional expression, the source filename, and 
line number is printed to s t d e r r , and the program ends. 



atan() 

H eader: 
Syntax: 
Description: 
Parameters: 



math.h 

double at an( doubl e dVal ue) ; 

Returns the arctangent of dva i ue. 

dvai ue — The value for which arctangent is desired. 
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T he arctangent of dva i ue. 

doubl e dTangent 

dTangent = a t a n ( 0 . 2 5) ; 

AISO Seeatan2( ) . 



atan2() 

Header: math.h 

Syntax: double atan2( doubl e dValuel, double 

dVal ue2) ; 

Description: Returns the arctangent of dvai uei and dva i u e2 . 
Parameters: dvai uei — Thefirst value whose arctangent is desired. 

dvai ue 2 — The second value whose arctangent is desired. 
Returns: The arctangent of dvai uei and d va i ue2 . 

Example: double dTangent 

dTangent = a t a n 2 ( 0. 25, 3.2); 

Note: Also seeatani i . 



atexit() 

Header: stdlib.h 

Syntax: i n t a t e x i t ( v o i d ( * f u n c t i o n ) ( v o i d ) ) ; 

Description: Tellsthe system to call f unct i on when the program ends. 

Parameters: f unct i on — Pointer to the function to be called. 

Returns: Zero if at exi t( ) is successful. 

Example: atexi t(OurExi tFuncti on) ; 

N ote: Functionsarecalled in a last in, first out manner. T hereis no way 
to remove a function once it has been passed using at exi t ( ) . 
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atof() 

H eader: 
Syntax: 
Description: 
Parameters: 

Returns: 
Example: 

Note: 



math.h & stdlib.h 

double atof( const char * szString); 

Converts characters to a double value. 

szstring — Pointer to a string containing thecharacter represen- 
tation of the double number. 

A doublevalue. 

dVal ue = atof ( " 1 2 3 4. 5 6 ") ; 
/* dVal ue wi I I be 1 2 3 4. 5 6 */ 

Conversion continues until thefirst invalid character is reached. 
You can tester r no to determine any errors that occurred. 



atoi() 

Header: stdlib.h 

Syntax: int atoi (const char * szString); 

Description: Converts characters to a short integer value. 

Parameters: s z st r i n g — Pointer to a string containing thecharacter represen- 
tation of the integer. 

Returns: A short integer. 

Example: nVal ue = atoi ( " 1 2 3 4 ") ; 

/ * nVal ue wi I I be 1 2 3 4 */ 

Note: Conversion continues until thefirst invalid character is reached. 

You can tester mo to determine any errors that occurred. 



atolQ 

H eader: 
Syntax: 



stdlib.h 

long atoi (const char * szString) 



526 



ANSI C's Library Functions 



Description: Converts characters to a long (32-bit) integer. 

Parameters: szst r i ng — Pointer to a string containing the character 
representation of the integer. 

Returns: A long integer. 

Example: I Va I u e = at ol ( " 1 2 3 4 5 6 7 8 ") ; 

/ * lvalue will be 12345678 */ 

Note: Conversion continues until thefirst invalid character is reached. 

You can tester r no to determine any errors that occurred. 




bsearch() 

H eader: 
Syntax: 



Description: 
Parameters: 



Returns: 

Example: 

Note: 



search. h & stdlib.h 

void * bs ea r c h ( ( v o i d * k e y , const void * b a s e , 
si z e _ t n u m, si z e _ t width, 
int ( *compare) ( const void * e I e ml , 

const void 

* e I e m2 ) ) ; 

Searches a sorted list for the given key value. 

k e y — Poi nter to the key value to search for. 

b a s e — Pointer to the array to search. 

n u m— N umber of elements in the array being searched. 

wi dt h — Size of an element in thearray being searched. 

c o mp a r e — Pointer to a function that is doing the compare. 

Either a pointer to a matching element or nul l if the key was not 
found in the list. 

/* See Chapter 10, "Data Management: Sorts, Lists, 
and Indexes."*/ 

Thearray to besearched must besorted; if it isnot, theresultsare 
undefined. 
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callocQ 

H eader: 
Syntax: 
Description: 
Parameters: 

Returns: 
Example: 

Note: 



malloc.h & stdlib.h 

void * cal I oc( si zet nCount, si z e _ t nSize); 

Allocates an array. 

nco u nt — N umber of elements. 

nsi ze — Size of each array element. 

Either a pointer to the array or null if the memory couldn't be 
allocated. 

i nt * p 0 u r Array; 

pOurArray = cal I o c ( 100, s i z eof ( i nt ) ) ; 

Thecal i o c ( ) function initializes the memory to zero. 



ceilQ 

H eader: 

Syntax: 

Description: 

Parameters: 

Returns: 

Example: 

Note: 



math.h 

double c e i I ( d o u b I e d Value); 

Returns the smallest integer value not less than dvai ue. 
dvai ue— Number for which the ceiling value is desired. 
The integer ceiling value, converted to a double. 

dCei I = cei I ( ■ 2. 2) ; 
/ * d Cei I wi I I be -2.0 */ 



Seet i 



oo r ( 



clearerrQ 

H eader: 
Syntax: 
Description: 



stdio.h 

void cl ear er r ( Fl LE * f i I e po i n t er ) ; 

Clears an existing end of file or other error condition for the 
given file. 
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Parameters: 

Returns: 

Example: 



Note: 



fi lepoi nter — Pointer to a stream file. 
No return value. 

if ( f er r o r ( OpenF i I e) ) 



{ 



} 



c I ea r er r ( Ope n F i I e) 



Seef er r or ( ) and f o p e n ( ) 




clock() 

H eader: timeh 

Syntax: cl o c k_ t cl ock(voi d); 

Description: Providesthenumberofclockticks(amountofCPU time) used by 
the program since it started. 

Parameters: None. 

Returns: CPU time. 

Example: printf("CPU time is %d\n", clock!) / 

CL0CKS_ PE R_ SEC) ; 

Note: The time returned is not elapsed time, but actual CPU time. In 

multitasking systems, returned time varies greatly from elapsed 
time. You convert thistimereturned by dividing it with themacro 
clocks per sec which is defined in timeh. 



cos() 

H eader: 

Syntax: 

Description: 

Parameters: 

Returns: 



math.h 

double cos( doubl e dVal lie) ; 

Returns the cosine of dva i ue (in radians), 
dvai ue — Value to compute the cosine of. 

COSineof dVal ue. 



529 



Part IV • Documentingthe Differences 



Example: 
Note: 



d Returned = cos(0.5) 
/* d Ret u r n ed wi I I be 0. 8 7 7 5 8 3 */ 



When dvai ue is a large value, the result may not be significant. 



coshQ 

Header: math.h 

Syntax: double cosh( doubl e dVal ue) ; 

Description: Returns the hyperbolic cosineof dvai ue (in radians). 

Parameters: dvai ue — Valueto compute the hyperbolic cosineof. 

Returns: H yperbolic cosine of dvai ue. 

Example: d Ret u r ned = cosh( 0. 5) 

/ * d Ret u r ned wi I I be 1.1 2 7 6 */ 

Note: When d value is a large value, the result may not be significant. 



ctime() 

Header: timeh 

Syntax: char * c t i me ( c o n s t t i me _ t * T i me B u f f e r ) ; 

Description: Converts the time pointed to by n me But f er into a printable 
format. 

Parameters: Ti me But f er — Pointer to a data object of type ti me t , properly 
initialized (perhaps by using t i me { ) ). 

Returns: Pointer to a character string, which is formatted as the example: 

F r i j un 2 6 1 5:1 7:0 0 1 9 9 2 \ n\ 0 

Example: t i me _ t OurTime = t i me ( N U L L ) ; 

p r i n t f ( c t i me ( &0u r Ti me ) ; 

Note: ThisfunCtionisequaltOCallingascti me( I ocal t i me(Ti me B uffer ) ) . 
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difftimeO 

H eader: 
Syntax: 

Description: 

Parameters: 

Returns: 
Example: 




Note: 



tirneh 

double d i f f t i me ( t i me _ t starttime, t i me _ t 
e n d t i me ) ; 

Computes and returns the difference between startti me and 
endt i me (in seconds). 

starti me — Time interval start. 

endt i me — Time interval end. 

Doubletimedifference, in seconds. 

t i me _ t S t a r t T i me = t i me ( N U L L ) ; 

t i me _ t E n d T i me ; 

char szBuffer[ 100] ; 

p r i n t f ( " Wa i t a few seconds, and press 

return\n"); 
gets( szBuffer) ; 
E n d T i me = t i me ( N U L L ) ; 
pri ntf( "You waited %f seconds\n", 

d i f f t i me ( E n d T i me , St a r t T i me ) ; 

D on't forget that the difference is in seconds. 



div() 

H eader: 
Syntax: 
Description: 

Parameters: 
Returns: 



stdlib.h 

d i v _ t divfint numerator, int denominator); 

Returns both the quotient and remainder from the division of 

n u me r a t o r by d e n o mi n a t o r . 

n u me r a t o r — I nteger value to be divided, 
denomi nat or — Integer valueto divide by. 
Structured i v t containing the result of the division. 
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Example: 



Note: 



d i v _ t Di v Res u I t ; 

Di v Res u I t = di v( 100, 3) ; 

Also seei di v( ) . 



exit() 

Header: process.h & stdlib.h 

Syntax: void exi t ( i nt n E x i t Code) ; 

Description: Causes the program to end. 

Parameters: n e x i t code — An integer passed back to the parent process. 

Returns: Does not return. 

Example: exit(o); 

Note: On M S-DOS systems, only thelow order byte of n e x i tcode is 
available. 



exp() 

H eader: math.h 

Syntax: double exp( double dValue); 

Description: Returns the exponential valueof dvai ue, such that exp(x)=e x 

Parameters: dvai ue — Value whose exponential value is desired. 

Returns: Exponential value of dva i ue. 

Example: double d Ex p ; 

d E x p = exp{ . 5) ; 
/ * d E x p will be 1. 6 4 8 7 */ 

Note: An e range error occurs if dvai ue is too large. 
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fabs() 

Header: math.h 

Syntax: doubl e fabs( d o u b I e dVal ue) ; 

Description: Returnstheabsolutevalueof dvai ue. 

Parameters: dvai ue— Double for which absolute value is desired. 

Returns: T he absolute value of dvai ue. 

Example: doubl e d Abs = f a bs ( - 0. 2) ; 

/ * d Abs wi I I be 0.2 */ 

Note: Also seeabsi ) . 

fclosel) 

H eader: stdio.h 

Syntax: i nt fcl ose( Fl LE * OpenFi I e) ; 

Description: Closes theopen stream filepointed to by op e n f i i e. 

Parameters: open f i i e — Pointer to a f i l e structure. 

Returns: Zero if thefunction is successful. 

Example: f cl ose( OpenFi I e) ; 

Note: If thefunction fails, then err no contains the error code. 

feof() 

H eader: stdio.h 

Syntax: i nt f e of ( Fl LE * OpenFi I e) ; 

Description: Tests for an end of file condition on OpenFi i e. 

Parameters: open f i i e — Pointer to a f i l e structure for an opened file. 

Returns: A non-zero if the file is at end of file. 
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Example: 
Note: 



int nEndOfFi I e = feof ( OpenFi I e) ; 

/* nEndOfFi I e is zero if not end of file */ 

Also seed ear er r ( i for clearing the end of file condition. 



ferror() 

H eader: stdio.h 

Syntax: int f er r or ( Fl LE * OpenFi I e) ; 

Description: Tests for any error conditions for the stream file op e n f i i e. 

Parameters: OpenFi i e— Pointer to a f i le structurefor an opened file. 

Returns: A non-zero if there is an error associated with OpenFi i e. 

Example: int n E r r o r = f er r or ( OpenFi I e) ; 

/* nError will be zero if no errors. */ 

Note: Also seed ear er r ( i for clearing errors. 



fflushO 

H eader: stdio.h 

Syntax: int ffl ush(FI LE * OpenFi I e) ; 

Description: For output files, ffi usho writesany unwritten characters in the 
file's buffer to thefile. For input files, f f i usho will undo thelast 
unget c ( ) . If OpenFi i e isNun, then all open files are flushed. 

Parameters: OpenFi i e— Pointer to a f i le structurefor an opened fileor null 
for all files. 

Returns: A non-zero if an error is associated with OpenFi i e. 

Example: int nError = fflush(OpenFile); 

/* nError is zero if no errors in flushing. 

*/ 

Note: Also see c\ ear er r ( ) for clearing errors. Frequently flushing 

output files hdps prevent data loss if the computer crashes. 
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fgetcO 

H eader: 

Syntax: 

Description: 

Parameters: 

Returns: 

Example: 
Note: 




stdio.h 

i nt f g e t c ( Fl LE * OpenFi I e) ; 

G ets the next character from op e n f i i e . 

OpenFi i e— Pointer to a fi le structure for an opened input file. 

Thenext character from OpenFi i e , or eof if either an error occurs 
or the end-of-file is reached. 

char chChar = ( char)fgetc( OpenFi I e) ; 
/* chChar contains the next character 
f r om t he file. */ 

Also seed earerri ) for clearing errors. Getting singlecharacters 
atatimecan beinefficient; if possible, uset get s( ) to get an entire 
line at a time. 



fgetposO 

H eader: stdio.h 

Syntax: i nt f get pos( FILE * OpenFi I e, f post * 

Position); 

Description: Saves the current position of OpenFi i e in the variable pointed to 

by P o s i t i o n . 

Parameters: open f i i e — Pointer to a f i l e structurefor an opened input file. 

posi ti on— Pointer to a variableof typet post . 
Returns: A non-zero if there is an error. 

Example: f post Position; 

f get pos ( Open F i I e , & P o s i t i on) ; 
/* Position will contain the file current 
position. */ 

Note: Usually, you uset seeki i to reset thefileto the point indicated by 

Posi t i on . 
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fgetsO 

H eader: stdio.h 

Syntax: char * f g e t s ( c h a r * s z B u f f e r , i n t 

BufferSi ze r FILE * OpenFi I e) ; 

Description: Getsa string from thefile, stopping when either a newline 
character is encountered or 
BufferSi z e - 1 characters have been read. 

Parameters: szBuf f er — Buffer to store characters in. 

Buff e r s i z e — Size of the buffer. 

OpenFi i e— Pointer to a fi le structure for an opened input file. 
Returns: null if an error occurs; otherwise, sz Buff er is returned. 

Example: char szBuffer[ 100] ; 

gets( szBuffer, sizeof(szBuffer), 
OpenFi I e) ; 

Note: A newline character is never discarded. Don't assume there will 

always be a newline character; test to be sure. 



floor!) 

H eader: 
Syntax: 
Description: 

Parameters: 
Returns: 

Example: 

Note: 



math.h 

doubl e floor(double d V a I ue) ; 

Returnsthel argest i n teger ( converted to dou bl e) th at i s n ot greater 

than dVal ue . 

dvai ue — Value to use for the computation. 

Double value representing the largest integer not larger than 

dVal ue. 

doubl e d F I oor = f I oor( 3. 14159) ; 
/* d F I oor will be 3.0 */ 

Seecei I ( ) . 
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fmod() 

H eader: 
Syntax: 
Description: 
Parameters: 

Returns: 
Example: 

Note: 



math.h 

double fmod( doubl e x , double y ) ; 

Returns the remainder of x / y. 
x— N umerator, doublevalueto bedivided. 
y— Denominator, doublevalueto divide by. 
Remainder of the division. 

double d Mo d = f mod ( 3. 1415 9, 3.0); 
/ * d Mo d will be 0. 14159 */ 

I f y is non-zero, then the result has the same sign as x . 




fopen() 

H eader: 
Syntax: 

Description: 
Parameters: 



Returns: 

Example: 

Note: 



stdio.h 

FILE * fopen( const char * s z F i I e N a me , const 
char * Mode) ; 

Opens thefile, using the filename and modeprovided. 

szFi i e Name— Pointer to a character string containing a valid 
filename. 

mo de — Pointer to a character string containing themodedescrip- 
tor characters. 

Pointer to a fi le structure for thefile that was opened or null if 
thefile couldn't be opened. 

FILE * Our Fi I e; 

0 u r F i I e = fopen( "ourfi I e.dat", " r " ) ; 

The mode characters include those shown in Table 14.1, which 
follows. Each character can be used with other characters except 
where indicated otherwise. 
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Table 14.1. File opening mode letter descriptions. 


Mode 




\- lldl dLLcl 


U caLI ipuuil 


r 


Read (cannot be used with write, w, or append, a ). 


w 


W rite (cannot be used with read, r , or append, a ). 


a 


Append (cannot be used with read, r , or write, w). 


b 


Binary (cannot be used with text, t ). 


t 


Text (cannot be used with binary, b). 


+ 


Opens for both read and write (used with read and write). 




With w/ritp tri inratpc; filp to 7Prn Ipnnth 

V V 1 LI 1 VV 1 1 LC, LI U 1 1 L-ULdj NIC LU £.0 U 1 CI 1 LJ LI 1 ■ 


fprintfO 




H eader: 


stdio.h 


Syntax: 


i nt fpri ntf( Fl LE * OpenFile, const char * 




s z F o r ma t , . . . ) ; 


Description: 


D oes formatted output to the file pointed to by open Fi i e. 


Parameters: 


openFi i e — Pointer to an open stream (text mode) file. 




s z f o r ma t — A format descriptor string. 


Returns: 


N u m ber of characters written . 1 f n egati ve, th en an error occu rred . 


Example: 


fpri ntf(stderr, "The number one is" 




" %d \ n " , 1 ) ; 


Note: 


See the section on pri ntf ( ) format codes at the end of this 




chapter. 


fputcO 




H eader: 


stdio.h 


Syntax: 


i nt fputc(int nCharacter, FILE * OpenFile); 
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Description: 
Parameters: 

Returns: 
Example: 

Note: 




Writes the character contained in ncharacter to the file pointed 

tO by OpenFi I e . 

ncharacter — Character to be written. 

openFi i e— Pointer to an opened file. 

The character written or eof if an error occurs. 



f put c ( ' ! ' , 
f put c { ' \ n' 



s t d e r r ) ; 
st der r ! 



U seer r no to determine what error occurred. 



fputsO 

H eader: stdio.h 

Syntax: i n t f p u t s ( c o n s t char * s z B u f f e r , FILE * 

OpenFi I e) ; 

Description: Writes the string pointed to by s z b u f f e r to the file specified. 
Parameters: sz But f er — Pointer to a string to be written. 

openFi i e— Pointer to an opened file. 
Returns: eof if an error occurs, otherwise a non-negative value. 

Example: f put s( " Now is the t i me. . . \ n" , st der r ) ; 

Note: Alsoseet pri ntt ( ) . 



freadO 

H eader: 
Syntax: 

Description: 



stdio.h 

size_t f r e a d ( v o i d * Array, size_t 
ElementSize, size_t 
Number El ement s , FILE * 
OpenFi I e) ; 

Reads an array from thefile. 
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Parameters: 



Returns: 
Example: 



Note: 



Array — Pointer to the array (which may be a character array). 
ei eme nt si ze — Sizeof each element in the array. 
Number ei e mem s — N umber of elements in array, 
open f i i e — Pointer to an opened file. 
N umber of elements read. 

i n t n T i me s [ 2 0] ; 

f read( nTi mes, sizeof(nTimes[0]), 

sizeof(nTimes) / sizeof(nTimes[0]), 
Open F i I e) ; 

The number of elements read may be less than the number 
requested. 



freed 

H eader: 
Syntax: 
Description: 

Parameters: 

Returns: 

Example: 

Note: 



malloc.h & stdlib.h 

void f r e e ( v o i d * Pointer); 

Freesthememory(whichwasallocatedwithcai i oc( ) ormai i oc( ) ) 
pointed to by Poi nt er . 

poi nter — Pointer to a dynamically allocated memory block. 
No return value. 

i nt * n A r r a y = calloc(20, si zeof ( i nt ) ) ; 
f r ee ( n Ar r a y ) ; 



See c a 1 1 o c < ) and ma 1 1 



oc 



freopenf) 

H eader: 
Syntax: 



stdio.h 

FILE * f reopen( const char * s z F i I e N a me , 

const char * szMode, FILE * 
Open F i I e) ; 
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Description: 



Parameters: 



Returns: 
Example: 



Note: 




Allows a specific fileto be associated with an already opened file. 
Usually used to allow s t d i n , or one of the other pre-opened 
standard files, to be associated with a specific file. 

szFi i e Name — Pointer to the filename of the file to be opened. 

szMode — M odestring (seef openi i for details). 

openFi i e— Pointer to an opened file. 

Pointer to a fi le structure. 

FILE * File = f r e o p e n ( " 0 u r F i I e . d a t " , " r " , 
st di n) ; 

/* s c a nf ( ) will now read from 'OurFile.dat' 

*/ 

Also seat o pe n ( ) . 



frexpO 

H eader: 
Syntax: 

Description: 

Parameters: 



Returns: 
Example: 



math.h 

double f r ex p ( do u bl e dVal ue , i n t * 
nExponent ) ; 

N ormalizes a floating point number and places the exponent in 
the integer pointed to by nExponent . 

dvai ue— Floating point value to benormalized. 

nExponent — Pointer to an integer to hold the exponent (2 raised 

tO the .power nExponent ). 

The parameter dva i ue normalized. 

i nt nExponent ; 

double d N o r ma I = f r e x p ( 3 . 1 4 1 5 9 , 

&nExponent ) ; 
/* dNormal will be 0.7 8 5 3 9 8, nExponent will 
be 2 */ 



Note: 



In the preceding example 0.785398 * (2 * 2) =3.14159. 
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fscanf() 

H eader: stdio.h 

Syntax: int fscanf(FILE * Open File, const char * 

s z F o r ma t , . . . ) ; 

Description: Reads formatted input from thespecified stream (text mode) file, 
with the format of the input determined by the format string 

pointed tO by sz For mat . 

Parameters: openFi i e — Pointer to an opened file. 

sz For mat — Format string (see the section on format strings 
below). 

Returns: Number of argumentsscannedorEOF if theend ofthestream was 

reached. 

Example: f scant ( Ope n F i I e, "%s %d", szBuffer, 

& n C o u n t ) ; 

Note: t scanti i has a variable number of arguments determined by the 

format string. 



fseek() 

H eader: 
Syntax: 

Description: 

Parameters: 



Returns: 



stdio.h 

int fseek(FILE * OpenFi I e , long lOffset, int 
nOr i g i n ) ; 

Moves the file pointer for the specified file to the position 
specified byi offset relative to the origin specified by n or i gi n. 

openFi i e — Pointer to an opened file. 

i ot t set — Whereto move thefile pointer. 

nori gi n — Origin point from which to compute the new file 
pointer position. 

Zero if the function is successful, non-zero if it fails. 
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Example: f seek( OpenFi I e, 2 5 61, SEEK_CUR); 

/ * Skip the next 2 5 6 bytes */ 

Note: Table 14.2 lists the valid seek origins. 

Table 14.2. File seek origins. 



0 ri gi n poi nt D escri pti on 



SEEK 


SET 


F rom the start of the file (a negative val ue for the offset 
value is not acceptable). 


SEEK 


CUR 


From thecurrent position of the file's pointer (either a 
negative or positive value for the offset val ue is accept- 
able). 


SEEK 


END 


From theend of thefile (a negative valuefor the offset 
value is acceptable). 



You cannot seek before the beginning of a file, but you can seek past theend 
of thefile. 



fsetposO 

H eader: 
Syntax: 

Description: 

Parameters: 

Returns: 



stdio.h 

i nt fsetpos(FILE * OpenFi I e , const f post * 
Position); 

Sets a file's position, using the f po s t 
variable filled in using f get pos ( ) . 

OpenFi i e— Pointer to an opened file. 

posi t i on— Pointer to an t pos t data 
object, filled in using f get post ) . 

Zero if successful, otherwise a non-zero value. 
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Example: 



Note: 



f post Position; 

Position = 100; 

/* Position is now at byte 100. */ 

f set pos ( Open F i I e , &Pos i t i o n ) ; 

AISO Seef get pos(). 



ftellQ 

H eader: stdio.h 

Syntax: long ftel I (Fl LE * OpenFi I e) ; 

D escription: Returns the current read or write point for the specified file. 

Parameters: OpenFi i e — Pointer to an opened file. 

Returns: The read or write position for the file. 

Example: long I Position = f t e I I ( Op e n F i I e ) ; 

Note: The result received from f tei i ( ) can later be used with f see m ) 



fwriteO 

H eader: 
Syntax: 



Description: 
Parameters: 



Returns: 



stdio.h 

size_t fwrite(const void * Array, size_t 
ElementSize, size_t 
NumberEI ements, FILE * 
OpenFi I e) ; 

WriteSNumber El ements Of Array to the Specified file. 

Ar r ay — Pointer to an array (often a character string). 

ei ements i ze — Sizeof each element in the array. 

Number ei ement s — N umber of elements to write. 

OpenFi i e — Pointer to an opened file. 

N umber of elements written. If the returned value is less than 
NumberEi ements then an error occurred. 



544 



Example: 



Note: 



ANSI C's Library Functions 




i nt n A r r a y [ ] ={1,2,3,4,5,6,7,8,9}; 
f wr i t e ( n Ar r a y , 

s i z eof ( n Ar r a y [ 0 ] ) , 

si zeof( nArray) / s i z eof ( n Ar r a y [ 0 ] ) , 

OpenFi I e) ; 

Checker r no if an error occurred, to determi ne what the error is. 



getc() 

H eader: stdio.h 

Syntax: i nt get c ( Fl LE * OpenFi I e) ; 

Description: Gets the next character from the specified file. 

Parameters: OpenFi i e— Pointer to an opened file. 

Returns: The character retrieved from the file or eof if there is an error. 

Example: char chChar; 

chChar = (char)getc(stdin); 
/* Gets one character from the keyboard */ 

Note: Thisfunction is generally equal to f get c( ) except that it may be 

implemented as a macro. 



getchar() 

H eader: stdio.h 

Syntax: i nt getchar( voi d) ; 

Description: Gets the next character from stdi n. 

Parameters: None. 

Returns: The next character from stdi n. 

Example: char chChar; 

chChar = get char ( ) ; 

Note: Thisfunction is the same as using g etc (stdi 
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gets!) 

H eader: stdio.h 

Syntax: char * g e t s ( c h a r * szBuffer) ; 

Description: Getsthenextlinefromstdi n , until either theend of thes t d i n file 
is reached or until a newline character is encountered. 

Parameters: szBuffer — Pointer to a character string to hold the characters 
read. 

Returns: Pointer to s z But f er or null if an end of filecondition is encoun- 

tered. 

Example: char szBuffer! 100] ; 

gets) szBuffer) ; 

N ote: C areful : T here is no check for buffer overrun ! 1 1 may be better to 

usefgetso rather than thisfunction. 



gmtimeO 

H eader: 
Syntax: 

Description: 
Parameters: 
Returns: 
Example: 



Note: 



tirneh 

struct t m * g mt i me ( c o n s t t i me _ t * 
Ti meVal ue) ; 

Breaksdownn me va i ue and placestheresultintothetm structure, 
n mevai ue— Pointer to a t i me t variable. 
A retu rn ed poi n ter to a stru ctu re of type t m . 

t m Ti me St r uct ; 
t i me _ t OurTi me; 

OurTi me = t i me( NULL) ; 

TimeStruct = ( t m* ) g mt i me ( &0u r Ti me) ; 

Remember to consider the effects of different time zones and 
daylight savings time. 
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isalnum() 

H eader: ctypeh 

Syntax: int i s a I n u m( i n t Character); 

Description: Teststo seeif thespecified character isan alphanumeric character 
(a-z, A-Z, or 0-9). 

P arameters: character — The character to be tested. 

Returns: A non-zero if the character is alphanumeric or a zero if it is not. 

Example: if ( i sal num( ' a' ) ) 

p r i n t f ( " ' a ' is alphanumeric \ n " ) ; 

N ote: See i s a i p h a ( i . 




isalphaO 

H eader: 
Syntax: 
Description: 

Parameters: 

Returns: 

Example: 

Note: 



ctypeh 

int i sal p h a ( i n t Character); 

Tests to see if the specified character is an alphabetic character 
(a-z or A-Z). 

character — The character to be tested . 

A non-zero if the character is alphabetic or a zero if it is not. 



if ( i sal pha( ' a' 
p r i n t f ( * ' a ' 

See i sal num( ) . 



s alphabetic \ n " ) ; 



iscntr I () 

H eader: 
Syntax: 
Description: 



ctypeh 

int iscntrl(int Character); 

Tests to see if the specified character is a control character 
C\x00'-'\xlf'). 
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Parameters: 
Returns: 

Example: 
Note: 



character — Thecharacter to be tested. 

A non-zero if the character is a control character or a zero if it is 
not. 

if ( i sent r I ( ' \ a' ) ) 

p r i n t f ( " ' \ a ' is a control character" 
" (the bell?) \ n") ; 

See i s a I p h a ( ) . 



lit 

H eader: 

Syntax: 

Description: 

Parameters: 

Returns: 

Example: 

Note: 



ctypeh 

i nt i sdi gi t ( i nt Character); 

Tests to see if the specified character isa numeric digit (0-9). 

character — Thecharacter to be tested. 

A non-zero if thecharacter isa numeric digit or a zero if it is not. 

if ( i sdi gi t ( ' r ) ) 

p r i n t f ( " ' 1 ' is a digit \ n " ) ; 

See i sal num( ) . 



isgraph() 

H eader: ctypeh 

Syntax: i n t i sgraph( i nt Character); 

Description: Tests to see if the specified character is a printable character 
(except a space). 

Parameters: character — Thecharacter to betested. 

Returns: A non-zero if the character is printable, or a zero if it is not. 

Example: if ( i sgr a p h ( chChar ) ) 

put c ( c hCha r ) ; 

Note: To test for a blank character, usei sspacet ) . 
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H eader: 

Syntax: 

Description: 

Parameters: 

Returns: 

Example: 

Note: 




ctypeh 

int i s I o we r ( i n t Character); 

Tests to see if the specified character is lowercase (a- z). 

character — The character to be tested . 

A non-zero if the character is lowercase or a zero if it is not. 

if ( i si ower ( chChar ) ) 
put c( chChar ) ; 

AISO See i supper( ) . 



i sprint!) 

H eader: ctypeh 

Syntax: int i s p r i n t ( i n t Character); 

Description: Tests to see if the specified character is a printable character 
(including spaces). 

P arameters: character — The character to be tested. 

Returns: A non-zero if the character is printable, or a zero if it is not. 

Example: if ( i spr i nt ( chChar ) ) 

put c ( chChar ) ; 

Note: To test for all characters except for a blank character, use 

i sgr a p h ( ) . 



ispunct() 

H eader: 
Syntax: 
Description: 



ctypeh 

int ispunct(int Character); 

Tests to see if the specified character isvalid punctuation, such as 
the period (.), comma (,), or exclamation point (!). 
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Parameters: character — The character to betested. 

Returns: A non-zero if the character is punctuation or a zero if it is not. 

Example: if ( i spunct ( chChar ) ) 

put c ( c hCha r ) ; 

N ote: N one. 



isspaceO 

H eader: 
Syntax: 
Description: 

Parameters: 
Returns: 

Example: 
Note: 



ctypeh 

int isspace(int Character); 

Tests to see if the specified character is a valid whitespace 
character. 

character — Thecharacter to betested. 

Anon -zero if th e ch aracter i s a val i d wh i tespace ch aracter or a zero 
if it is not. 



if ( i s s p a c e ( chChar ) ) 
put c ( c hCha r ) ; 

Totestforanon-blankcharacter,usei sgr aph( ) .Valid whitespace 
characters in elude those shown in Table 14.3: 



Table 14.3. Valid whitespace characters. 



C haracter D escription (hex value) 

' ' The space character. 

\f T he form feed character (\xOC). 

\n' T he newline character (\xOA'). 

\r The carriage return character (\xOD'). 

\t T he tab character (\x09'). 

' \ v The vertical tab character (\xOB'). 
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isupper() 

H eader: ctypeh 

Syntax: int i supper( i nt Character); 

Description: Tests to see if the specified character is uppercase (A-Z). 

P arameters: character — The character to be tested. 

Returns: A non-zero if the character is uppercase or a zero if it is not. 

Example: if ( i supper ( chChar ) ) 

put c ( c hCha r ) ; 

Note: To test for a lowercase character, usei si ower ( ) . 



isxdigit() 

H eader: 
Syntax: 
Description: 

Parameters: 
Returns: 

Example: 
Note: 



ctypeh 

int isxdigit(int Character); 

Tests to see if the specified character is a valid hexadecimal digit 
character (a-f, A-F, and 0-9). 

character — The character to be tested . 

A non-zero if the character is a valid hexadecimal digit or a zero if 
it is not. 



if ( i sxdi gi t ( chChar ) ) 
put c ( chChar ) ; 

To test for a decimal-only digit, usei sen gi u ) 



labs() 

H eader: 
Syntax: 
Description: 



math.h & stdlib.h 

long I a b s ( I o n g lvalue); 

Returnsthe absolute valueof i vai ue. 
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Parameters: 

Returns: 

Example: 

Note: 



i vai ue — The value for which absolute value is desired. 
Absolute value of i va i ue. 

long I Returned; 

I Returned = I abs ( - 2 3 4 5 5 6) ; 

Also seeabsi ) . 



IdexpO 

H eader: 
Syntax: 
Description: 

Parameters: 

Returns: 
Example: 

Note: 



math.h 

double I dexp( doubl e lvalue, int nPower); 

M ultiplies a floating point value by two raised to nPower ( i vai ue 

* 2 n Powe r ) . 

i vai ue — Value to multiply. 
nPower — Power to raise two by. 

(l Val ue * (2 * nPower )) 



if ( I d ex p ( . 7 8 5 3 9 8, 2) 
p r i n t f ( " I t wo r ks ! \ n " ) 



3. 1 4 2 5 9) 



See f r e x p ( 



ldiv() 

H eader: 
Syntax: 

Description: 

Parameters: 



stdlib.h 

I d i v _ t I d i v ( I o n g numerator, long 
denominator); 

Returns both the quotient and remainder from the division of 

n u me r a t o r by d e n o mi n a t o r . 

numerator — Long integer value to be divided, 
denomi nat or — Long integer value to divide by. 
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Note: 
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Structure i di v_t containing the result of the division. 

I di v_t Di v Re s ul t ; 

Di v Re s u I t = I di v ( 100, 3) ; 

Also see d i *m ) . 



localeconv() 

H eader: 
Syntax: 
Description: 

Parameters: 

Returns: 

Example: 

Note: 



localeh 

struct I conv * I ocal econv( voi d) ; 

Returnsthestructuretypei conv filled in with appropriatevalues 
for the location. 

None. 

Pointer to an i conv structure. 

I c on v OurConversi ons; 

OurConversi ons = ( I conv * ) I o c a I e c o n v ( ) ; 

Seeset i ocal e( ) for more information. 



H eader: 
Syntax: 

Description: 

Parameters: 

Returns: 

Example: 



timeh 

struct t m * I o c a I t i me ( c o n s t t i me _ t * 
Ti meVal ue) ; 

Breaks down Ti me va i ue, and places the result into the tm 
structure. 

Ti mevai u e — Pointer to a t i me t variable. 
A pointer to a returned structure of type t m. 

t m T i me S t r u c t ; 
t i me _ t 0 u r T i me ; 

OurTi me = t i me( NULL) ; 

TimeStruct = (tm * ) I o c a I t i me ( &Ou r Ti me ) ; 
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Note: 



Remember to consider the effects of different time zones and 
daylight savings time. 



log!) 

H eader: 

Syntax: 

Description: 

Parameters: 

Returns: 

Example: 

Note: 



math.h 

double I o g ( d o u b I e d V a I lie) ; 

Computes the natural logarithm (basee) of dvai ue. 
dvai ue — Value to compute the natural logarithm of. 
Logarithm of dvai ue. 

pri ntf("Log of 3.14159 is %f " , 
I og( 3. 14159) ) ; 
/ * Log of 3.14159 is 1.1 4 4 7 2 9 */ 

Seei o g 1 0( ) . 



loglOO 

H eader: 

Syntax: 

Description: 

Parameters: 

Returns: 

Example: 

Note: 



math.h 

doubl e I o g 1 0 ( doubl e dVal ue) ; 

Computes the logarithm (base 10) of dvai ue. 
dvai ue — Value to compute the logarithm of. 
Logarithm of dvai ue. 

pri ntf("LoglO of 3.14159 is %f " , 
I o g 1 0 { 3. 14159) ) ; 
/ * LoglO of 3.14159 is 0.4 9 7 1 5 */ 

See I o g () . 



longjmpO 

H eader: 



setjmp.h 
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Syntax: void I o n g j mp ( j mp _ b u f jump buffer, int 

n R e t u r nCode) ; 

Description: Restores the environment to what was saved in j umpbuffer by 
setjmpo, which causes execution to continue from the call to 

set j mp( ) , With set j mp( ) returning n Ret ur nCode . 

Parameters: j umpbuffer — Buffer of typej mp_buf initialized by set j mp( ) . 

nRet ur nCode — Value that set j mp( i returns when i ongj mp( ) is 
called. 

Returns: longjmpu does not return, execution continues with set j mp( ) . 

Example: See Figure 14.1 for an example. 

Note: Seesetj mpo . 

As Figure 14.1 shows, the error handler usually uses i ongj mp( ) to get past a 
part of the program that is causing an error. Since this error handler doesn't have any 
access to thefailing function's variables, it cannot make any changes or set any flags. 



Install SIGFPE handler 
using signal Q 








Our SIGFPE handler 


1 


RetirnCode = 
seljmpO, 




Return i.r::ing 
longjmpO 
ReturnCode = 1 










Figure 14.1. Program flow using set j mpo and i ongj mp( ) 
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mallocl) 

H eader: 

Syntax: 

Description: 

Parameters: 

Returns: 

Example: 



Note: 



malloc.h & stdlib.h 

void * ma I I o c ( si z e _ t SizeToAl locate); 

Allocates memory (uninitialized). 

si zeToM i ocate — Sizeof the memory block to allocated. 

Pointer to the memory block allocated or null if the memory 
could not be allocated.. 

i n t * n A r ray; 

nArray = (int * ) ma I I o c 

( si zeof ( i nt ) * 5 0 0) ; 
me ms e t ( n A r r a y , 0, sizeof(int) * 500) 

M emory allocated using mai i oc( ) is never initialized; however, 
memory allocated using cai i oc( i is. 



mblenO 

Header: stdlib.h 

Syntax: int mbl en( const char * szString, si z e _ t 

nCo u nt ) ; 

Description: Examinesncount characters, starting from the location pointedto 
byszst r i ngjookingforthenumberofbytesinthenextmultibyte 
character. 

Parameters: szst r i ng — Pointer to the first byte of the multibyte character. 

Returns: Zero if szst r i ng i s n u l l , -1 if thisisnot a multibyte character or 

the number of characters in the multibyte character. 

Example: int n Count; 

n Co u n t = mb I e n ( s z St r i n g , 3 ) ; 

Note: See the other multibyte character functions, which follow. 
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mbstowcsO 

H eader: 
Syntax: 

Description: 

Parameters: 



Returns: 

Example: 

Note: 




stdlib.h 

size_t mbstowcs(wchar_t * pWideChar, const 
char * szString, si z e _ t 
nCount ) ; 

Converts the multibyte characters pointed to by szst i ng into 
wide character codes and places the result into pwidecnar, 
converting up to n count characters 

pwi dechar — Pointer to a string buffer to receive the wide 
character conversion. 

szst r i ng — Source multibyte character string. 

n Count — Size Of pWi deChar . 

N umber of characters converted or -1 if an error occurs. 
No example provided. 

AISO Seembl en( ) and mbtowc( ) . 



mbtowcO 

H eader: 
Syntax: 

Description: 

Parameters: 



stdlib.h 

i nt mbt o wc ( wc ha r _ t * pWideChar, const 
char * pMul ti Byte, si z e _ t 
nCount ) ; 

Converts a single multibyte character pointed to by p mu i ti Byte 
into a wide character code and places the result into pwi dechar , 
examining up to nCount characters 

pwi dechar — Pointer to a buffer to receive the wide character 
conversion. 

p mu 1 1 i Byte — Source multibyte character string. 

nCount — Size Of pWi deChar . 
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Returns: 

Example: 

Note: 



N umber of characters converted or -1 if an error occurs. 
No example provided. 

AISO See mb I en() and mbt o wc s ( ) . 



memchrO 

H eader: 
Syntax: 

Description: 

Parameters: 



Returns: 
Example: 



Note: 



memory.h & string.h 

void * me mc h r ( c o n s t void * szString, int 
chChar, si z e _ t nLength); 

Searches for the first occurrence of ch char inszstring limiting 
the search to the first n l e n g t h characters. 

szstring — Pointer to the string to search. 

c h c h a r — C haracter to search for. 

nLength — Number of characters to search inszstri ng. 

Pointer to the located character or null if it cannot be found. 

char szStringM = {"Now is the time for 
all good me n " } ; 

p r i n t f ( " I s it the t i me %s " , 
me mc h r ( s z S t r i n g , ' f ' , 
strlen(szString)); 
/ * Wi I I print Is it the t i me for all good me n * / 

Seememcmpo and mems et ( i . N oticethat me mc hr ( i doesn't assume 
the string is a n u l l terminated character string. 



memcmpl) 

H eader: 
Syntax: 

Description: 



memory.h & string.h 

int me mc mp (const void * pBufferl, const void 
* p B u f f e r 2 , size_t nLength); 

CompareSUp tO nLengt h Characters Of pBufferl with p B u f f e r 2 , 
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Parameters: 

Returns: 
Example: 




Note: 



pBuf f er 1 — Pointer to thefirst buffer. 

pBuffer 2— Pointer to the second buffer. 

mengt h — N umber of bytesto compare. 

Zero if they are equal, < 0 if pBuf fen is less than pBuff e r 2 , 
or >0 if pBuff en is greater than p b u f f e r 2 . 

char szStri ngl[ ] = {"Now is all the time 

for all good me n " } ; 

char szStri ng2[] = {"Now is not the time 

for all good me n " } ; 

if ( me mc mp( s z St r i n g 1 , szStri n g 2 , 
st r I en( s zSt r i ngl) ) == 0) 

{ 

p r i n t f ( " ' %s ' ' %s ' are equal " , 
szStri ngl, 
szStri ng2); 

} 

/* Will not print since the strings are not 
equal */ 

Seememchro and mems et ( i . N oticethatmemc mp( i doesn't assume 
the string is a null terminated character string. 



memcpyO 

H eader: 
Syntax: 

Description: 
Parameters: 



memory.h & string.h 

void * me mc p y ( v o i d * p Destination, const 
void * pSo u r c e, si z e _ t 
nLengt h) ; 

CopiesnLengt h bytes from p s o u r c e topDesti nati on.Sourceand 
destination must not overlap. 

pDesti nati on — Pointer to the destination buffer. 

p s o u r c e — Poi nter to the source buffer. 

nLengt h — N umber of bytesto copy. 
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Returns: 
Example: 



Note: 



Thepointer pDest i n a t i on. 

char szStri ngl[ ] = {"Now is all the time 

for all good me n " } ; 

char szString2[] = {"Now is not the time 

for all good me n " } ; 

memcpy(szStri ngl, szStri ng2, 

st r I en( szSt r i n g 2 ) ) ; 
p r i n t f ( " ' %s ' and ' %s ' " , 

szStri ngl, 

s z St r i n g 2 ) ; 

Seememmoveu and mems et ( i . N oticethat me mc py ( i should not be 
used where the source and destination overlap. 



memmovef) 

H eader: 
Syntax: 

Description: 
Parameters: 



Returns: 
Example: 



string.h 

void * memmove(void * p Des t i n a t i o n , const 
void * pSo u r c e, si z e _ t 
n L e n g t h ) ; 

CopieSn Length bytesfrom pSo u r c e tOpDesti nat i on . Sourceand 

destination may overlap. 

pDesti nati on — Pointer to the destination buffer, 
ps o u r c e — Pointer to the source buffer, 
n l e n g t h — N umber of bytes to copy. 

Thepointer pDest i nat i on . 

char s z S t r i n g 1 [ 1 0 0 ] = {"Now is all the 

time for all good 
me n " } ; 

char szStri ng2[100] = {"Now is not the 

time for all good 
me n " } ; 
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me mmo ve( &szStri ng2[ 10] , szString2, 

strlen(szString2)); 
p r i n t f ( " ' %s ' " , 
s z St r i n g 2 ) ; 

Note: Seememcpyi ) and memset ( ) . Noticethat memcpyi ) should not be 

used where the source and destination overlap, while memmovei i 
works correctly when thereisoverlap; however, thisfunction may 
be slower. 



memset() 

H eader: 
Syntax: 

Description: 
Parameters: 



Returns: 
Example: 



Note: 



memory.h & string.h 

void * me ms e t ( v o i d * pBuffer, int nByte, 
si z e _ t nLength); 

FillSnLengt h bytes Of p Buf f e r with nByte. 

p Buf f e r — Buffer that isto be filled. 
nByte— Byte to fill the buffer with, 
mengt h — H ow many bytes to fill. 
T he pointer p Buf f e r . 

int * Ar r ay; 

Array = (int *)malloc 

( si zeof ( i nt ) * 100) ; 

me ms e t ( A r r a y , 0, sizeof(int) * 100); 
/* Zeros out the allocated array */ 

Thisfunction is very useful to initialize both auto and allocated 
data objects, which are not otherwise initialized. 



mktimeO 

H eader: 
Syntax: 



tirneh 

t i me _ t mkt i me( st r uct t m * Ti me) 
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Description: 

Parameters: 

Returns: 

Example: 

Note: 



Converts thetm time structure to calendar time (Coordinated 
Universal Time). If thevaluesareoutof range, they are adjusted 
as necessary. 

n me— Pointer to at m time structure. 
A t i me t structure. 

struct t m Ti me ; 

me ms e t ( T i me , 0 , s i z e o f ( T i me ) ; 
/ * fill in Ti me wi t h values */ 

mkt i me ( &T i me) ; 

Also see ti men . 



modf() 

H eader: 
Syntax: 

Description: 
Parameters: 



Returns: 
Example: 



Note: 



math.h 

double modf ( doubl e dValue, double * 
d I n t eg r a I ) ; 

Computes the fractional and integral parts of dvai ue. 

dvai ue— Real number for which integral and fractional parts are 
desired. 

di nt e g r a i — Pointer to a doublethat will receive theintegral part 

Of dVal ue. 

The fractional part of dvai ue. 



double dlntegral; 
double dFract i onal 



/ * dlntegral wi 
Seef mod( ) . 



mo d f ( 4 . 1 2 3 4 , 

&d I n t eg r a I ) ; 
be 4, dFract i onal wi I I be 0.1 2 3 4 */ 



offsetofO 

H eader: 



stddef.h 
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Syntax: si z e _ t off setoff composi te Structure, name 

Member ) ; 

Description: Returns the offset (in bytes) of Member from the beginning of 

Structure. 

Parameters: structure — A structure. 

Member — A member in St r uct ur e. 
Returns: Offset in bytes. 

Example: struct t m Ti me; 

pri ntf( "the offset of t m_ y e a r is %d " , 
of f s et of ( s t r u c t t m, t m_ y ea r ) ) ; 

Note: Remember that structure is the type name, not the variable 

name. 



perrorO 

H eader: 
Syntax: 
Description: 

Parameters: 

Returns: 

Example: 



stdio.h & stdlib.h 

void perror( const char * szPrefix); 

Prints an error message corresponding to err no to stderr . If 
szPrefix is not null, that string is prefixed to the message 
printed. 



Zero if successful, otherwise a non-zero value. 

/* Set errno to an error value (usually set by a library 
function) * / 

errno = EACCES; 

perror( "DUMMY ERROR HERE") ; 



/* prints: DUMMY ERROR HERE: Permission denied */ 
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pow() 

H eader: 
Syntax: 
Description: 
Parameters: 

Returns: 
Example: 

Note: 



math.h 

d o u b I e pow( double x, double y) ; 

Raises x to the power y. 
x — N umber to raise to power y . 
y — Power to raise x to. 
x to the power y . 

p r i n t f ( " 3 to the power 5 = %f \ n " , 
pow( 3. 0, 5.0)); 
/* Prints: 3 to the power 5 = 2 4 3.0 0 00 0 0 */ 

See e x p ( ) . 



printfQ 

H eader: stdio.h 

Syntax: i n t pri ntf(const char * s z F o r ma t , . . . ) ; 

Description: Prints, to st do ut formatted output as defined by sz For mat . 

Parameters: sz For mat — A format descriptor string. 

Returns: Numberof characters written . I f n egati ve, th en an error occu rred . 

Example: printf("The number one is %d\n", 1); 

N ote: See the section on pri n t f { ) format codes at the end of this 
chapter. 

putc() 

H eader: stdio.h 

Syntax: int putc(int nChar, FILE * OpenFile); 

Description: Writesnchar to thestream fileopen File. 
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P arameters: n c h a r — C haracter to be written . 

openFi i e— Pointer to an opened file. 

Returns: Character nch a r if successful, otherwise e of. 
Example: putci'A' , stdout); 

Note: Same as f put c( i except that put c ( ) can be implemented as a 
macro. 

putcharf) 

H eader: stdio.h 

Syntax: i nt putcharf i nt nCha r ) ; 

Description: Writesnchar to thestream filest do ut . 

P arameters: n c h a r — C haracter to be written . 

Returns: Character nch a r if successful, otherwise e of. 
Example: putchari 'A' ) ; 

Note: Sameasf putci nchar , stdout i except that put c( ) canbeimple- 
mented as a macro. 

puts() 

H eader: stdio.h 

Syntax: int puts( const char * szString); 

Description: Writesszst r i ng to thestream files t d o ut . 

Parameters: szst r i ng — Pointer to the character string to be written. 

Returns: Non-zero positive value if successful, otherwise eof . 

Example: putchari "Now is the t i me . \ n " ) ; 

Note: Also seet put s( i and put cu . 
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qsort() 

H eader: 
Syntax: 



Description: 
Parameters: 



Returns: 

Example: 

Note: 



search. h & stdlib.h 

void qsort(voi d * Array, si z e _ t 

NumberEI ements, si z e _ t 
ElementSize, int ( *compare) 
(const void *, const void *)); 

Sorts Array using a quicksort method. 

Array — Pointer to an array to be sorted (can be an array of any 
type). 

NumberEi ement s — N umber of elements in Ar r ay to besorted. 

El ement Si z e — Size Of each element in Array. 

c o mp a r e — P oi n ter to a f u n cti on to do com pare of array el ements. 
No return value. 

See Chapter 10, "Data M anagement: Sorts, Lists, and Indexes." 

With a creative compare function, qsortu can do any sort 
imaginable. 



raised 

Header: signal.h 

Syntax: int r a i s e ( i n t nExcepti on) ; 

Description: Simulates occurrence of an error condition. 

Parameters: nExcept i on — Theerror condition that isto be signaled. 

Returns: Zero if successful, otherwise a non-zero value. 
Example: r ai se( si gi nt) ; 

Note: This function is most useful when you have installed your own 
exception handler. See signal ( ) . 
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rand() 

Header: stdlib.h 

Syntax: i n t r a n d ( v o i d ) ; 

Description: Returnsa pseudorandom number in therangeof zero to rand max 
(usually 32767). 

Parameters: None 

Returns: Random number. 

Example: i nt nRandom = r a n d ( ) ; 

/* nRandom will be a random number */ 

N ote: D on't forget to seed the random number using s r a n d ( ) . 



reallocO 

H eader: 
Syntax: 

Description: 
Parameters: 

Returns: 
Example: 



Note: 



malloc.h & stdlib.h 

void * real I oc( voi d * pBuffer, si z e _ t 
n NewS i z e ) ; 

C hanges the size of the buffer poi nted to by p b u f f e r . 

pBuffer — Pointer to an allocated buffer. 

n News i ze— N ew sizefor the buffer (either smaller or larger). 

Pointer to a new buffer, with pBuffer 's contents copied to it or 
null if a new buffer could not be allocated. 

char * pBuffer = ma I I oc ( s i z eof ( c ha r ) * 100); 
s t r c py ( pBuffer, 

"Now is the t i me for all good men"); 
/* now shrink it... */ 

pBuffer = r e a I I o c 
(pBuffer, s t r I en ( pBuf f er ) + 1) ; 

/* This example shrinks the buffer to fit the contents 

*/ 

Always save thepointer in case the buffer can't be resized. Never 
refer to the old pointer after this function successfully returns 
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removed 

H eader: io.h & stdio.h 

Syntax: int remove) const char * s z F i I e N a me ) ; 

Description: Deletes the file with namethat is pointed to by s z f i i e Na me . 

Parameters: szFi i eNa me — Pointer to a character string containing the name 
of an existing file. 

Returns: Zero if successful, otherwise a non-zero value. 

Example: remove! "test . dat ") ; 

Note: Becareful to not deletea filethat iscurrently opened becausethe 

results may be unpredictable. 

renamed 

H eader: io.h & stdio.h 

Syntax: int rename (const char * s z 01 d N a me , const 

char * s z Ne wNa me ) ; 

Description: Renames files. 

Parameters: szoi dName— Pointer to a string that contains the old filename. 

szNewNa me — Pointer to a string containing the new filename. 
Returns: Zero if successful, otherwise a nonzero value. 

Example: rename! "01 dData. Dat", " NewDat a . Dat " ) ; 

Note: Very useful under PC DOS becauseitallowsrenamingafiletoa 

different directory. 



rewind!) 

H eader: 
Syntax: 



stdio.h 

void rewi nd( Fl LE * OpenFile); 
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Description: Resets thefile pointer for open Fi i e to the beginning of thefile. 

Parameters: openFi i e— Pointer to an opened file. 

Returns: No return value. 

Example: rewi nd( OpenFi I e) ; 

Note: M uch the same as calling f see k( openFi i e, 0, seekset) . 




scanf() 

H eader: 

Syntax: 

Description: 

Parameters: 

Returns: 

Example: 



Note: 



stdio.h 

i n t s c a n f ( c o n s t char * s z F o r ma t , . . . ) ; 

Reads from stdi n formatted input. 

s z fo r mat — Pointer to a string containing format codes. 

N umber of items that were scanned and stored or eof if the end 
ofthefilewasencoun tered . 

i nt i ; 

scant ("%d", &i ) ; 
/* i will be whatever (numeric) value 
entered */ 

Seethesection on scant ( ) format codesattheend of thischapter. 



setbufO 

H eader: 
Syntax: 

Description: 
Parameters: 

Returns: 



stdio.h 

void setbuf(FILE * OpenFi I e , char * 
pBuf f er ) ; 

Sets a buffer for the file op e n f i i e. 

openFi i e— Pointer to an opened file. 

pButter — Pointer to a buffer of at least bufsi z bytes. 

No return value. 
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Example: char szBuffer[ 123]; 

char * pBuf f er = ma I I o c ( B U F S I Z ) ; 

setbuf(stdi n, pBuf f e r ) ; 

printf("enter a stri ng\n") ; 

g et s ( s z Buf f er ) ; 

printf("enter a second stri ng\n"); 

g et s ( s z Buf f er ) ; 

pri ntf ("' %s' \ n", pBuffer); 



Note: Be sure the buffer is large enough (useBUFSi z). 

setjmpO 

Header: setjmp.h 

Syntax: int setj mp(j mp buf jumpbuffer); 

Description: Savestheenvironmenttoj u mp buf f er , which then can beused by 
longjmpo to return to the point saved. 

Parameters: j umpbuff er — a buffer of type j mp_ buf . 

Returns: setj mp { ) returns zero when being initialized or the return code 

specified by i ongj mp( ) , which will not be zero. 

Example: See Figure 14.2 for an example. 

N ote: See i o n g j mp ( ) . 



AsFigurel4.2 shows, theerror handler usually usesi ongj mp( ) to get past a part 
of the program that is causing an error. Because this error handler doesn't have any 
access to thefailing function's variables, it cannot make any changes or set any flags. 
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Our SIGFPE handler 




Th8 floaling point 
error causes a 
SIGFPE 
interrupt. 



Figure 14.2. Program flow using set j mp( ) and i ongj mp( 



setlocaleO 

H eader: locale.h 

Syntax: char * setl ocal e( i nt Category, const char 

Local e) ; 

Description: Sets thee at ego ry for the i ocai e. 
P arameters: category — C ategory toset(seeTablel4.4). 
Local e — Thelocaleto set. 
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Returns: String indicating the current locale. 

Example: set I ocal e< LC_ALL, "C"); 

N ote: Because most compilers and operating systems support only the 

"c locale, thisfunction doesn't have an effect. Asnew locales are 
added, thisfunction will bemoreuseful. Check the documenta- 
tion supplied with your compiler for other information. 



Table 14.4. Locale categories. 


Category 


Description 


L C _ A L L 


t ntire envi ronment. 


LC_ MONETARY 


m oney format. 


LCCOLLATE 


l on ate sequence. 


LC_ NUMERI C 


N umber format. 


LCCTYPE 


Character handling. 


C _ T 1 ME 


\ ime-reiatea items 


setvbuff) 




H eader: 


stdio.h 


Syntax: 


i nt setvbuf( Fl LE * OpenFile, char * pBuffer, 




int nMode, si z e _ t nSize); 


Description: 


Sets a buffer for thefileopenFi i e. 


Parameters: 


openFi i e — Pointer to an opened file. 




p b u f f e r — Pointer to a buffer. 




nMode — M odefor the file buffer (see Table 14.5). 




nsi ze — Buffer. 


Returns: 


Zero if successful, otherwise a nonzero value. 
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Example: char szBuffer [ 123] ; 

char * p B u f f e r = ma I I o c ( B U F S I Z * 2 ) ; 

setvbuf ( stdi n, pBuff er, J OFBF, BUFSI Z * 

2); 

pri ntf( "enter a s t r i n g \ n " ) ; 
gets) szBuffer) ; 

pri ntf( "enter a second stri ng\n") ; 
gets( szBuffer) ; 
pri ntf ("' %s' \n", pBuffer); 

Note: Besurethebufferislargeenough to beeffective. Table 14.5 shows 

the allowable modes. 

Table 14.5. Function setvbufO's modes. 



Mode Description 



1 OFBF 


Theinputand output will be fully buffered. 


1 OLBF 


The output will be line buffered (buffer is flushed 




when a newline is encountered or the buffer is full). 


1 ONBF 


No buffering is performed (All parameters except 




openFi i e and n Mod e areignored). 


signal!) 




H eader: 


signal. h 


Syntax: 


void (* si g n a 1 ( i n t nSignal, 




void ( * f u n c t i o n ) ( i n t ) ) ) ( i nt ) ; 
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Description: Tdls the system to call function whenever the error condition 
specified by n s i g n a i is raised by either an error condition or the 

raised function. 

Parameters: nsi g n a i — Theerror condition to be modified. 

function — T hefunction to be called when theerror condition is 
raised. See Table 14.6 for other values for fu net i on. 

Returns: si g err if an error occurs, otherwise the previous signal handler. 

Iffuncti on isoneof thedefined constants shown in Table 14.6, then theaction 
described will betaken. Notice that after theerror condition occurs, si gnai ( ) must 
again be called because the system first makes a call to s i g n a i ( nsi gnai , si g_dfd . 

Table 14.6. Signal predefined actions. 



Defined value Description 



SI G_ 


DFL 


The default action will occur. 


SI G_ 


1 GN 


Thecondition will beignored. 


SI G_ 


AC K 


Used in some systems to tell the operating system 






the handler is ready to receive the next error signal. 




H eader: 


math.h 


Syntax: 


double s i n( doubl e dVal ue) ; 


Description: 


Computes thesineofdvai ue. 


Parameters: 


dvai ue — Value to compute the sine of. 


Returns: 


Thesineofdvai ue. 


Example: 


dVal ueSi n e =s i n( . 5) ; 

/ * dVal ueSi ne wi 1 1 be 0.4 7 94 */ 
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Note: 




Seeacos( ) , asi n{) , and cost) 



sinh() 

Header: math.h 

Syntax: double si nh( doubl e d Va I u e ) ; 

Description: Computes the hyperbolic sineof dvai ue. 

Parameters: dvai ue — Valueto compute the hyperbolic sineof. 

Returns: The hyperbolic sineof dvai ue. 

Example: dValueSine = s i n h ( . 5 ) ; / * dValueSine will be 0.5210 */ 

Note: Seeacosi ) , asi n( ) , and cos( ) . 



H eader: 
Syntax: 

Description: 

Parameters: 

Returns: 
Example: 

Note: 



stdio.h 

int sprintf(char * pBuffer, 

const char * s z F o r ma t , . . . ) ; 

Prints, to the buffer pointed to by pBuf f er , formatted output as 
defined by szFor mat . 

p But f e r — Pointer to a destination buffer. 

szFormat — A format descriptor string. 

N umber of characters written. If negative, then an error occurred. 

char sz Buf f er [ 100] ; 
spri ntf ( szBuffer , 

"The number one is %d \ n " , 1 ) ; 

Besurethedestination buffer is large enough. Seethesection on 
format codes at the end of this chapter. 
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sqrtO 

Header: math.h 

Syntax: doubl e sqrt( d o u b I e dVal ue) ; 

Description: C omputes the square root of dvai ue. 
Parameters: dvai ue — Value for which square root is desired. 
Returns: Square root of dvai ue. 

Example: double dSquareRoot = s q r ZXt ( 2 ) ; 

/* dSquareRoot will be 1.41 */ 

N ote: T he argument must not be negative. 

srandf) 

Header: stdlib.h 

Syntax: void srand( unsi gned int nSeed); 

Description: Seeds (sets the starting point) of the random number generator. 
Parameters: nSeed — A seed value. 
Returns: No return value. 

Example: srand( ( unsi gned) ti me( NULL) ) ; 

Note: The sequence of numbers returned by rand o is identical if 

identical seeds are used. Using the ti meo function assures a 
reasonably random starting point. 



sscanfO 

H eader: 
Syntax: 

Description: 



stdio.h 

int sscanf ( const char * szl nput , 

const char * s z F o r ma t , . . . ) ; 

Reads from the buffer pointed to by szi nput , formatted input. 
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Parameters: sz i n put — Pointer to a buffer containing the string to be read. 

s z fo r mat — Pointer to a string containing format codes. 

Returns: N umber of items that were scanned and stored or e of if the end 

ofthefilewasencoun tered . 

Example: i nt i ; 

char s z I npu t [ ] = { " 1 2 3 4 " } ; 

scant (szl nput, "%d", &i ) ; 
/ * i wi I I be 1 * / 

Note: Seethesection on scant o formatcodesattheendofthischapter. 

strcatf) 

H eader: string.h 

Syntax: char * str cat (char * sz Destination, 

const char * sz So u r ce ) ; 

Description: C oncatenatesthestring pointed to by s z s o u r c e toszDest i nat i on. 
Parameters: szDest i nat i on — String that will haveszsour ce appended to it. 

sz Source — The String to append tOszDesti nati on. 

Returns: Pointer szDesti nati on. 

Example: char szSt r i ng[ 100] = {"Now is the time"}; 

s t r c a t ( s z S t r i n g , " for all good me n " ) ; 
/* szString will be Now is the time for all 
good me n * / 

N ote: Besurethedestination islargeenough to hold theresultant string 

and that it has been properly initialized. Thedestination can bea 
string of zero length. 



strchr() 

H eader: 
Syntax: 



string.h 

char * strchr(const char * szString, i nt c h C h a r ; 
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Description: 
Parameters: 

Returns: 
Example: 



Note: 



Searches for thefirst occurrence of ch char in szstri ng. 
s z s t r i n g — Pointer to the string to be searched, 
c h c h a r — C haracter to search for. 

Pointer to the first occurrence of chchar or null if it is not 
found. 

char szStri ng[ 100] = 

{"Now is the t i me for all good me n " } ; 

pri ntf("Not the t i me %s " , 

s t r c h r ( s z St r i n g , ' f ' ) ) ; 
/* Will print Not the time for all good men */ 

See me mc h r ( ) . 



strcmpO 

H eader: 
Syntax: 

Description: 

Parameters: 

Returns: 
Example: 



string.h 

i n t strcmpf const char * szStri ngl, 
const char * szStri ng2); 

Compares two strings and returns a value indicating if they are 
equal or if one is less than the other. 

szstri ngi — Thefirst string to compare. 

szstri ng 2 — The second string to compare. 

Zero if they are equal, <Oifszstri ngi is less than s z st r i n g 2 , or 
>0 if szst r i ngi is greater than szst r i n g 2 . 

char szStringlM = 

{"Now is all the time for all good me n " } ; 

char s z St r i n g 2 [ ] = 

{"Now is not the time for all good me n " } ; 



{ 



f ( s t r c mp ( s z St r i n g 1 , szStri ng2) == 0) 

pri n t f ( " ' %s ' ' %s ' are equal " r 
szStri ngl, 
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Note: 



szStri ng2); 



} 



/* Will not print since the strings are not equal 

*/ 

Seememchr ( ) . N oticethat me mc mp ( ) doesn't assumethestring isa 
null terminated character string. 



strcollO 

H eader: 
Syntax: 

Description: 

Parameters: 

Returns: 
Example: 



string.h 

i nt s t r c o I I ( c o n s t char * szStringl, const char * 
szSt r i n g 2 ) ; 

Compares two strings using the collating sequence selected by 
setiocaieo and returns a value indicating whether they are 
equal or if one is less than the other. 

szst r i ngi — Thefirst string to compare. 

szstri ng 2 — The second string to compare. 

Zero if they areequal, <Oifszstri ngi is less than s z s t r i n g 2 , or 
>0 if szst r i ngi is greater than szst r i n g 2 . 

char szStringlM = 

{"Now is all the time for all good men"}; 

char szStri ng2[] = 

{"Now is not the time for all good men"}; 



Note: 



if ( s t r c 0 1 I ( s z St r i n g 1 , szStri ng2) == 0) 

{ 

p r i n t f ( " ' %s ' ' %s ' are equal", 
szStri ngi, 
szStri ng2); 

} 

/* Will not print since the strings are not equal 

*/ 

Seememchr o . N oticethat me mc mp ( ) doesn't assumethestring isa 
null term i n ated ch aracter string.T hisfunction isequal tos t r c mp< ) 
when thedefaultcollatingsequencespecified bylocale- c- isused. 
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strcpyl ) 

H eader: 
Syntax: 

Description: 
Parameters: 

Returns: 
Example: 

Note: 



string.h 



char * strcpy(char * szDesti nati on, 

const char * s z So u r c e ) ; 

CopiesthestringtoszDest i nati on thatispointed to bysz so u r c e . 
szDesti nation — A string that has szsource copied to it. 

szSo ur ce — The String Copied tO sz Dest i n a t i on . 
Pointer szDesti nati on. 

char s z S t r i n g [ 1 0 0 ] = {"Now is the t i me " } ; 

s t r c p y ( s z S t r i n g , " for all good me n " ) ; 
/* szString will be for all good men */ 

Besurethedestination islargeenough to hold theresultant string. 



strcspn() 

H eader: 
Syntax: 

Description: 

Parameters: 

Returns: 
Example: 



string.h 

si z e _ t st rcspn( const char * szString, 
const char * s z Ch a r s ) ; 

Returnsthe length of the initial string that does not contain any 
characters found in szcnars . 

szString — Pointer to a string to be searched. 

szchars — String containing characters to be searched for. 

Length of the initial string that contains no characters from 

sz Chars, up tO the length OfszStri ng. 

char szStr i ng[ 100] = 

{"Now is the t i me for all good me n . " } ; 

i n t n C o u n t = s t r c s p n ( s z S t r i n g , " f z x " ) ; 



pri ntf("Never a good time %s " , 
&szSt r i ng[ nCount ] ) ; 
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Note: 



/* will print Never a good time for all good men. 

*/ 

Also Seestrspnf ) . 



strerror() 

H eader: string.h 

Syntax: char * strerror( i nt nError); 

Description: Returns a pointer to a string describing the error contained in 

nError . 

Parameters: nError — Error value (usually from e r r n o ). 

Returns: Pointer to an error message or a message indicating a message 

doesn't exist for this error. 

Example: pri ntf( "Had an error: %s\n", 

strerror( E NOME M) ) ; 

Note: Seeermo and the header fileer r n o. h. 



strftimeO 

H eader: 
Syntax: 

Description: 

Parameters: 



tirneh 

size_t strftime(char * szBuffer, si z e _ t 

nBufferSize, const char * 

s z F o r ma t , const struct t m * T i me ) ; 

Prints to szBuffer the time contained in Ti me according to the 
format specified in szFormat (see Table 14.7 for the format 
characters). 

szBuffer — Pointer to the destination buffer that will receive the 
formatted time string. 

nBuf f erSi z e — Size Of s z Bu f f er . 

s z fo r ma t — Pointer format string. 
Ti me— Pointer to at m time structure. 
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Returns: Thenumberof characters placed in sz Buff er or null if an error 

occurs. 

Example: M me _ t Our Time; 

OurTi me = t i me ( NULL) ; 

strfti me( szBuffer, si zeof(szBuffer) , 
"Today is %A %B %d , %Y", 
I o c a I t i me ( &0u r Ti me ) ) ; 
p r i n t f ( " %s \ n " , s z B u f e r ) ; 
/* Will print Today is Friday June 2 6, 1 9 92 */ 



N ote: See th e format characters in Tablel4.7. Thisfunction m akes th e 

creation of attractive time displays easy. 

Table 14.7. Function strfti me()'s format codes. 
Format Description 

%a Abbreviated weekday name. 

%a Full weekday name. 

%b Abbreviated month name. 

%b Full month name. 

%c Full dateand time (like c t i men ) representation 

appropriate for the locale. 

%d N umeric day of the month. 

%h H our in 24-hour format (00-23). 

%i Hour in 12-hour format (01-12). 

%i Day of the year (001-366). 

%m Month (01-12). 

%m Minute (00- 59). 

%p AM/PM indicator for a 12-hour clock. 

%s Seconds (00-61). 
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%u Week of the year as a decimal number; Sunday is 

taken asthefirst day of the week (00-53). 

%w Day of the week, (0-6; Sunday is 0). 

%w Week of the year; M onday is taken as the first day of 

the week (00-53). 

%x D ate representation for current locale. 

%x Time representation for current locale. 

%y Year without the century (00-99). 

%y Year with the century. 

%z Time zone name or abbreviation; no characters if time 

zone is unknown. 

%% Percent sign. 




strlen() 

H eader: 

Syntax: 

Description: 

Parameters: 

Returns: 

Example: 



Note: 



string.h 

size_t strl en(const char * szString); 

Returns the length of a string. 

szstri ng— Pointer to the string for which length is desired. 
N umber of characters in szst r i ng (excluding the terminating 

NULL ). 

char szStri ng[ 100] = 

"Now is the time for all good progra mme r s to..."}; 
p r i n t f ( " L e n g t h of ' %s ' is \ n %d " , 

szString, strl en( szStri ng) ) ; 
/* the length printed is 46 */ 

Thisfunction returnsthenumber of charactersin thestring, not 
the defined size. To get the defined size, use si zeof ( ) . 



583 



Part IV • Documenting the Differences 



strncatO 

H eader: 
Syntax: 

Description: 

Parameters: 



Returns: 
Example: 



Note: 



string.h 

char * s t r nc a t ( c h a r * s z Des t i n at i o n , const char * 
szSource, si ze_t nCount ) ; 

C on catenates n c o u n t characters of string pointed to by s z s o u r c e 

to s z De s t i n a t i o n . 

szDesti nati o n — String that will haveszsource appended to it. 

szSo ur ce — String tO append tOszDesti nati on. 

n c o u n t — N u m ber of ch aracters f rom s z s o u r c e to appen d . 

Pointer szDesti nati on. 

char szStri ng[ 100] = {"Now is the t i me " } ; 

strncatf szStri ng, " for all good me n " , 15); 
/* szStri n g will be Now is the time for all good m 

*/ 

Besurethedestination islargeenough to hold theresultant string, 
and that it has been properly initialized. The destination can bea 
string of zero length. 



strncmpO 

H eader: 
Syntax: 

Description: 
Parameters: 



string.h 

int strncmp (const char * szStringl, const char * 
szStri n g 2 , si z e _ t nCount); 

C om pares up to ncou nt ch aracters of th e two strings and retu rn s 
a value indicating whether they areequal or if one is less than the 
other. 

szstri ngi — Thefirst string to compare, 
szstri ng 2 — The second string to compare, 
n c o u n t — N u m ber of ch aracters to com pare. 
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Zero if they areequal, <Oifszstri ngi is less than s z s t r i n g 2 , or 
> 0 if s z s t r i n g 1 is greater than s z s t r i n g 2 . 

char szStringl[] = 

{"Now is all the time for all good men"}; 
char szStri ng2[] = 

{"Now is all the time for all Bad men"}; 



Note: 



if ( s t r n c mp ( s z St r i n g 1 , szStri ng2, 20) ==0) 

{ 

p r i n t f ( " ' %s ' ' %s ' are equal", 
szStri ng 1 , 
szStri ng2); 

} 

/* Will print since the strings are equal 
for the first 20 characters*/ 

See s t r c mp( ) . 



strncpyl) 

H eader: string.h 

Syntax: char * strncpy(char * sz Destination, const char * 

szSource, size_t nCount); 

Description: CopiestoszDest i n at i on uptoncount characters from the string 
pointed to byszsource. 

Parameters: szDest i nat i on — String that will haves z sour ce copied to it. 

szSo ur ce — String Copied tOszDesti nati on. 

n c o u n t — N umber of characters to copy. 
Returns: Pointer szDesti nati on. 

Example: char szSt r i ng[ 100] = {"Now is the time"}; 

strncpy(szString, " for all good men", 10); 
/* szString will be for all g */ 

N ote: Besurethedestination islargeenough to hold theresultant string. 
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string.h 

char * st r pbr k( const char * szString, const char * 
szCharacters) ; 

Finds the first occurrence of any character from szCharacters 

found in szSt r i ng . 

szstri ng — Pointer to a string to search. 

szCharacters— Pointer to a string containing characters to 
search for. 

Pointer to the first character found in szstring that is in 

szCharacters. 
char szStringlM = 

{"Now is all the time for all good me n " } ; 
char * pChars; 

p C h a r s = s t r p b r k ( s z S t r i n g 1 , " f z x y " ) ; 

if ( pCha r s ) 

{ 

pri ntf( "found at ' %s ' \ n " , 
pCha r s ) ; 

} 

/* Will print found at 'for all good men' */ 

strrchr() 

Header: string.h 

Syntax: char * strrchr( const char * szString, int chChar); 

Description: Finds the last occurrence of chch a r found in szstri ng. 
Parameters: szstri ng — Pointer to a string to search. 

c h c h a r — C haracter to search for. 



strpbrkQ 

H eader: 
Syntax: 

Description: 

Parameters: 

Returns: 
Example: 
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Pointer to the last occurrence of chch a r found in szst r i ng. 

char s z St r i ng 1 [ ] = 

{"Now is all the time for all good men"}; 
char * pChars; 

pChars = s t r r c hr ( s z St r i ngl , 'a'); 



{ 



f ( pChars) 

pri ntf( "found at ' %s ' \ n " , 
pChars); 



/* Will print found at 'all good men' */ 



strspn() 

H eader: 
Syntax: 

Description: 

Parameters: 

Returns: 
Example: 



string.h 

size_t strspn(const char * szString, const char * 
s z Ch a r s ) ; 

Returns the length of the initial string that contains characters 

found in szChars . 

s z s t r i n g — Poi nter to a string to be searched. 

s z ch a r s — String containing characters that must be contained. 

Length of the initial string that contains only characters from 

sz Chars, up tO the length OfszStri ng. 

char szSt r i ng[ 100] = 

{"Now is the time for all good men."}; 

char szOut put [ 100] ; 



mems et ( s z Out put , 0, s i z e of ( s z Ou t p u t ) ) ; 

st r n c p y ( szOut put , szString, 

s t r s p n ( s z St r i n g , " wo N si t e h " ) ) ; 
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Note: 



p r i n t f ( " %s " , 
szOut put ) ; 
/ * wi I I print Now is the t i */ 

Also see st r c s pn ( ) . 



strstrO 

H eader: 
Syntax: 

Description: 
Parameters: 

Returns: 
Example: 



Note: 



string.h 

char * strstr(const char * szString, const char ' 
szCharacters) ; 

Finds the first occurrence of szcharacters in szsti ng. 
szstring — Pointer to the string to search, 
s z c h a r a c t e r s — Pointer to the characters to search for. 
Pointer to the point where the characters were found. 

char szStr i ng[ 100] = 

{"Now is the t i me for all good me n . " } ; 

p r i n t f ( " ' %s ' " , s t r s t r ( s z S t r i n g , " me " ) ) ; 
/* will print 'me for all good men.' */ 

Basically a search for a substring in a string function. 



strtodO 

H eader: 
Syntax: 

Description: 
Parameters: 



stdlib.h 

double strtod(const char * szString, 
char ** pEnd); 

Converts thestring to afloating point number, stopping when an 
invalid character has been reached. The stopping point is stored 
in the variable pointed to by p End if p e n d is not null. 

szstring — Pointer to the string to convert. 

pEnd — Pointer to a string pointer. 
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Returns: 
Example: 



The floating point number converted. 

double d V a I ue; 

char szSt r i ng[ 100] = 

{" 1 2 3.3 4 Now is the t i me for all good men."}; 
char * p E n d ; 

dVa I ue = strtod(szString, & p E n d ) ; 

pri ntf( "Converted %f stopped at ' %s ' \ n " , 
dVal ue, 
pEnd) ; 



Note: 



/* 

* Prints: Converted 1 2 3.3 4 0 00 0 stopped at 
' Now is the time for all good men.' 

*/ 

See st r t ol ( ) . 



strtokO 

H eader: 
Syntax: 

Description: 
Parameters: 



Returns: 
Example: 



string.h 

char * strtok(char * szString, const char * 
szTokenSep) ; 

Breaks the string pointed to by s z st r i ng into tokens, when each 
token is separated by one (or more) of the characters found in 

s zTo kenSep . 

szst r i ng — Pointer to a string to break into tokens. This string 
will be modified, so use a copy if necessary. 

szTokenSep— Pointer to a string of token separators. 

Pointer toatoken from s z st r i ng. 

char szSt r i ng[ 100] = 

{"Now is the time for all good men."}; 

char szTokensl ] = {" . "}; 

char * pToken; 
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p r i n t f ( " ' %s ' \ n " , s z S t r i n g ) ; 

pToken = strtok( szStri ng, szTokens) ; 

do 

{ 

pr i ntf ( "Token ' %s ' \ n " , pToken) ; 
} while (pToken = st r t ok( NULL, szTokens)); 

p r i n t f ( " ' %s ' \ n " , s z S t r i n g ) ; 



/' 



* Prints: 

* 'Now is the ti me for all good men.' 

* Token ' Now' 

* Token 'is' 

* Token 'the' 

* Token ' t i me' 

* Token 'for' 

* Token 'all' 

* Token 'good' 

* Token ' me n ' 

* ' Now' 



Note: 



D on't forget that this function modifies the string passed. 



strtolQ 

H eader: 
Syntax: 

Description: 



stdlib.h 

long strtol ( const char * szString, char ** pEnd, 
i n t n Ba s e) ; 

Converts the string to a long integer number, stopping when an 
invalid character has been reached. The stopping point is stored 
in the variable pointed to by p e n d if p e n d is not null. The 
parameter nBase determines what base is used and must be 
either 0 or 2 through 36. If nBase is zero, then the base of the 
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number is determined from thenumber'sformat— if thenumber 
starts with ox orox, then it is base 16; if it starts with a zero, then 
base 8 is assumed; otherwise it is decimal based. 

Parameters: szstri ng— Pointer to the string to convert. 

pEnd — Pointer to a string pointer. 

nBase— Baseof thenumber to be converted. 
Returns: The long integer converted. 

Example: long I Value; 

char szSt r i ng[ 100] = 

{" 1 2 3.3 4 Now is the t i me for all good men."}; 
char * pEnd; 

lvalue = strtol ( szStri ng, & p E n d , 0) ; 

pri ntf( "Converted %l d stopped at ' %s ' \ n " , 
I Val ue, 
pEnd) ; 



Note: 



/* 

* Prints: Converted 123 stopped at 
'.34 Now is the time for all good men. 

*/ 

See s t r t o u I ( ) . 



strtouK) 

H eader: 
Syntax: 

Description: 



stdlib.h 

unsigned long int s t r t o u I ( c o ns t char * szString, 

char * * p E n d , 
int nBase); 

Converts the string to an unsigned long integer number, 
stopping when an invalid character isreached.T hestopping point 
isstoredinthevariablepointedtobypEnd if p e n d isnotNuu.The 
parameter nBase determines what base is used and must be 
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Parameters: 



Returns: 
Example: 



either 0 or 2 through 36. If nBase is zero, then the base of the 
number is determined from the number's format; if thenumber 
starts with ox or ox, then it is base 16; if it starts with a zero, 
then base 8 is assumed; otherwise it is decimal based. 

s z s t r i n g — Pointer to the string to convert. 

pEnd — Pointer to a string pointer. 

nBase — Base of the number to be converted. 

The long integer converted. 

unsigned long lvalue; 
char szStr i ng[ 100] = 

{" 1 2 3.3 4 Now is the t i me for all good men."}; 
char * pEnd; 



I Val ue = strtoul (szStri ng, &pEnd, 0) ; 

pri ntf("Converted %l d stopped at ' %s ' \ n " , 
I Val ue, 
pEnd) ; 

/* 

* Prints: Converted 123 stopped at '.34 Now is the time 
for all good men.' 

*/ 



Note: 



See s t r t o i 



strxfrm() 

Header: string.h 

Syntax: size_t strxfrm (char * sz Destination, const char * 

szSource, size_t nLength); 

Description: Copiesthestring pointed to bys z so ur c e to the buffer pointed to 
byszDesti nati on, using the collating sequence set by s et i ocai e 
o .Thefunction is identical to s t r n c p y ( ) when the locale is-c , 
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Parameters: 



Returns: 
Example: 




except thestring is not padded with n u l l characters when s z s o u r c e 
is shorter than mength. 

szDest i nat i on — Pointer to a buffer where szSource will be 
copied to. 

s z so u r c e — Pointer to a string to copy and convert. 

mengt h — M aximum number of characters to copy and convert. 

Length of the converted string. 

char szSource[ 100] = 

{"Now is the time for all good men."}; 

char szDesti nation! 100]; 



strxfrm( szDesti nati on, szSource, 
s t r I en ( s z So u r c e ) ) ; 

pri ntf( "Converted \ n ' %s ' \ n t o \ n ' %s ' \ n " 
szSource, 
s z De s t i n a t i o n ) ; 



Note: 



/* 

* Prints: 

* Converted 

* 'Now is the timefor all good men. 

* t o 

* 'Now is the timefor all good men. 

*/ 

See s t r nc py( ) 



system!) 

H eader: 
Syntax: 
Description: 



process.h & stdlib.h 

i nt system! const char * szCommand); 

Passes the string pointed to by sz command to the operating 
system's command processor. 
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Parameters: 
Returns: 

Example: 



Note: 



sz command — Pointer to a string containing an operating system 
command, or null to determine if thereis a command processor. 

If sz command i s null , non-zero if there is a command processor, 
otherwise a zero value. If szcommand isnot null, then zero if there 
was no error, or a non-zero value if the command processor 
couldn't be loaded. 

/* Check for command processor, and do a dir command if 
present */ 

i f ( system! NULL) ) 

{ 

s y s t e m( " d i r *.*"); 

} 

M ost operating systems have a loadable command processor. 



tan() 

H eader: 

Syntax: 

Description: 

Parameters: 

Returns: 

Example: 



Note: 



math.h 

double t an( doubl e d Va I u e ) ; 

Returns the tangent of dva i ue, measured in radians, 
dvai ue — Valuefor which tangent is desired. 
Thetangent of dvai ue. 

double d Res u I t ; 

d Res ul t = t an( 1. 5) ; 
/* dResul t wi I I be 14. 10142 */ 

Also see t a n h ( ) . 



tanh() 

H eader: 
Syntax: 



math.h 

double t a n h ( doubl e dVal ue) ; 
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Description: Returns the hyperbolic tangent of dvai ue, measured in radians. 
Parameters: dvai ue — Valuefor which hyperbolic tangent is desired. 
Returns: The hyperbolic tangent of dvai ue. 

Example: double dResult; 

dResul t = tanhfl. 5); 




Note: 



/ * dResul t wi I I be 0. 9 0 5 1 4 8 */ 

Also seetani ) . 



timed 

H eader: 
Syntax: 
Description: 
Parameters: 

Returns: 
Example: 



tirneh 

t i me _ t t i me ( t i me _ t * TimeValue); 

Returns the current calendar time encoded into at i me t type. 

n mevai ue — Pointer to atypet i met , which if not null , will also 
receive the time. 

The current time. 

char sz Buff er [ 100] ; 

t i me _ t Ou r Ti me ; 



OurTi me = t i me( NULL) ; 



Note: 



strfti me(szBuffer, si zeof(szBuffer) , 
"Today is %A %B %d , %Y", 
I o c a I t i me ( &Ou r Ti me ) ) ; 

p r i n t f ( " %s \ n " , s z B u f f e r ) ; 

/* Will print Today is Saturday June 2 7, 1 9 9 2 */ 

Also seest rf t i me( ) and ct i me( ) . Thefunction t i me ( ) 'sparam- 
eter is often null as shown in the preceding example. 
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tmpfileO 

H eader: stdio.h 

Syntax: file * t mpf i i e( voi d) ; 

D escription: C reates a temporary work fileand opens it for update. T hisfile is 
removed by the system either when it is closed or the program 
ends. 

Parameters: None. 

Returns: H andleto afileor null if the function fails. 

Example: FILE * TempWork = tmpfileO; 

Note: Be careful not to close the file in error because this removes the 



file. 



tmpnamf) 

H eader: 
Syntax: 
Description: 

Parameters: 

Returns: 

Example: 



Note: 



stdio.h 

char * t mp n a m( char * szFileName); 

C reates a save name for a temporary work file. T his function is 
used when t mpf i i e( ) cannot beused, such asin situations where 
thefile must be closed for some reason. 

szFi i eName — Pointer to a buffer to hold thefi lename. T hisbuffer 
must be at least l t mp n a m characters long. 

Pointer to the filename buffer. If szFi i eName is null, then the 
buffer is a static internal buffer. 

char s z B uf f e r [ L_ t mp n a m] ; 
tmpnam(szBuffer) ; 



printf("The temporary work file is '%s'\n", 
s z Buf f er ) ; 

Don't forget to remove the file when the program ends. 
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tolower() 

H eader: 
Syntax: 
Description: 

Parameters: 

Returns: 

Example: 

Note: 




ctypeh & stdlib.h 

i n t t o I o we r ( i nt c hCh a r ) ; 

Converts ch char to lowercase if it was originally uppercase. If 
chchar wasnot uppercase, then it is returned unchanged. 

c h ch a r — U ppercase letter to be converted to lowercase. 

The character converted to lowercase. 

p r i n t f ( " ' A' in I o we r c a s e is ' %c ' \ n " , 

tolower('A'); 
/ * Wi I I print 'A' in I o we r c a s e is ' a ' * / 

Seet o up per ( ) . 



toupper() 

H eader: ctypeh & stdlib.h 

Syntax: i n t toupper( i nt c h C h a r ) ; 

Description: Converts chchar to uppercase if it was originally lowercase. If 
chchar wasnot lowercase, then it is returned unchanged. 

Parameters: c h ch a r — Lowercase letter to be converted to uppercase. 

Returns: T he character converted to uppercase. 

Example: printffa' in uppercase is '%c'\n", 

t oupper ( ' a' ) ; 
/ * Wi I I print ' a ' in uppercase is 'A' * / 

Note: Seetoi oweri ) . 



ungetcO 

H eader: 
Syntax: 



stdio.h 

i nt ungetc( i nt chChar, FILE * OpenFile); 
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Thisfunction pushes back a character to thefileope n f i i e (which 
was opened for input). 

ch char — Character to be pushed back to the file, 
ope n f i i e — Pointer to an opened file. 
T he character that was pushed back. 

char szBuf f er [ 129] ; 

p r i n t f ( " P I e a s e press the ' b ' key: " ) ; 

szBuffer [ 0] = (char)getc(stdin); 

unget c( ' A' , s t d i n ) ; 

szBuffer [ 1] = (char)getc(stdin); 

p r i ntf("szBuffer has %2 . 2 s \ n " , szBuffer); 
/* Will print szBuffer has bA (if you type a ' b ' 
at the pr ompt ) */ 

Note: The character need not bethesameoneaswas last read. You may 

unget co only one character before the character is read or 

discarded (by a Call tO f seek( ) , f set pos( ) , Or r ewi nd( ) ). 

va_arg() 

H eader: stdarg.h 

Syntax: type va_arg( val i st param, type); 

Description: Obtains the next argument from a list of variable arguments to a 
function. 

Parameters: param— Parameter list pointer. 

type — Type of the next (to be fetched) parameter. 
Returns: Value of the parameter being fetched. 

Example: /* Program VARGS, written 17 June 1 9 99 by Peter D. 



Description: 
Parameters: 

Returns: 
Example: 
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Hi pson */ 

# i n c I u d e <l i mi t s . h> 

# i n c I u d e <stdarg. h> 

#i nc I ude < s t d i o . h > 

#i nc I u d e <s t d I i b . h > 

#d ef i n e TRUE 1 
#define FALSE ( ! TRUE) 

i nt AddLi st ( i nt n F i rst , . . . ) ; 

i nt OurErrorsfchar * Out put For mat , ...); 

void ma i n ( ) 
{ 

i nt nSum; 

nSum = AddLi st ( 1 0, 2 0, 3 0, 4 0, 5 0, 6 0, 7 0, 8 0, 
90, I NT_ Ml N ) ; 

(voi d) Our Errors! " %s - %d , %s\n", "First", 
n S u m, "Second"); 

} 

i nt AddLi s t ( 
i n t n F i r s t , 
. . . ) 

{ 

i nt nRet ur nVal ue = n F i rst; 
i nt n T h i sVal ue; 

v a _ I i s t Arguments; 

vastart ( Arguments, nFirst); 
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whi I e( ( nThi sVal ue = va_arg(Arguments, i n t ) ) ! 
I N T_ Ml N) 

{ 

n R e t u r nVal ue += nThi sVal ue; 

} 

va_end(Arguments) ; 
r et u r n ( n Ret u r n Va I u e ) ; 



n t OurEr rors( 

char * OutputFormat, 



{ 

v a _ I i st Arguments; 

va_start(Arguments, OutputFormat); 
vfpri ntf(stderr, OutputFormat, Arguments) 
va_end(Arguments) ; 
r et u r n ( 0 ) ; 



Note: 



} 

SeeC hapter 13, "All About H eader Files," for more information. 



va_end() 

H eader: 
Syntax: 
Description: 



stdarg.h 

void va_end(va_list param); 

Ends the processing of the variable number of arguments. 
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Parameters: para m— Variable argument list. 

Returns: No return value. 

Example: (Seeva.argo , preceding function described.) 

N ote: SeeC hapter 13, "All About H eader Files," for moreinformation. 




va_start() 

H eader: 
Syntax: 
Description: 
Parameters: 



Returns: 

Example: 

Note: 



stdarg.h 

void va_start(va_l i st param, previous); 

Starts processing of a variable number of arguments. 

param— va i i st variable, used bytheva functions. 

pr evi ous — N ameof thelast fixed parameter being passed to the 
called function. 

No return value. 

(Seeva.argo , previously described.) 

SeeC hapter 13, "All About H eader Files," for moreinformation. 



vf printf () 

H eader: 
Syntax: 

Description: 

Parameters: 

Returns: 



stdio.h 

i nt vf pr i nt f ( Fl L E * OpenFile, const char * 
szFormat, vajist VarArgs); 

Prints to thespecified file by using arguments passed by another 
function. 

openFi i e— Pointer to an opened file. 

s z fo r mat — Pointer to a string containing format information. 

varArgs — Variable argument list. 

N umber of characters written or a negative value if there was an 
error. 
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Example: /* Program VARGS , written 17 June 1 9 99 by 

Peter D. Hi pson */ 

#i n c I u d e <l i mi t s . h > 
#i nc I u d e <stdarg. h> 
#i n c I u d e < s t d i o . h > 
#i n c I u d e <s t d I i b . h > 

i nt OurEr rors( char * Out put For mat , ...); 

void ma i n ( ) 

{ 

i nt nSum = 100; 

( v o i d) Our Er r or s( "%s - %d , %s\ n", 

"First", n S u m, "Second"); 

} 

i n t Ou r E r r o r s ( 

char * 0 u t p u t F o r ma t , 
. . . ) 

{ 

v a _ I i st Arguments; 

va_start(Arguments, Output For mat ) ; 

vf pr i ntf ( st der r , Out put For mat , 
Ar g u me n t s ) ; 

va end(Arguments) ; 

r et u r n ( 0 ) ; 

} 

Note: Seevpr i ntf ( i . 



vprintfQ 

H eader: stdio.h 

Syntax: int vpri ntf( const char * szFormat, v a _ I i s t 

Va r Ar gs ) ; 
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Description: Prints to s t d o u t using arguments passed by another function. 

Parameters: s z fo r mat — Pointer to a string containing format information. 

varArgs — Variable argument list. 

Returns: Number of characters written or a negative value if there was an 

error. 

Example: /* Program VARGS, written 17 June 1 9 9 2 by 

Peter D. Hi pson */ 

# i n c I u d e <l i mi t s . h> 

#i nc I u d e <s t d a r g . h > 

# i n c I u d e < s t d i o . h > 

#i nc I ude <s t d I i b . h > 




Out put For mat , 



i nt Our Out put ( char 

void ma i n ( ) 

{ 

i nt nSum = 100; 

( voi d) Our Out put( " %s - %d , %s\n", 

"First", n S u m, "Second"); 

} 

i n t Ou r Ou t p u t ( 

char * Out p u t F o r ma t , 
. . . ) 

{ 

v a _ I i st Arguments; 

va_start(Arguments, OutputFormat); 
v p r i n t f ( OutputFormat, Arguments) ; 
va_end(Arguments); 
r et u r n ( 0 ) ; 

} 



Note: 



See v f p r i n t f ( ) 
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vsprintfO 

H eader: 
Syntax: 

Description: 

Parameters: 

Returns: 
Example: 



stdio.h 

i nt vspri ntf(char * szBuffer, const char * 
szFormat, v a _ I i s t VarArgs); 

Prints, using arguments passed by another function, to thebuffer 
pointed to by szBuf f er . 

szBuffer — Pointer to a buffer to write to. 

sz fo r mat — Pointer to a string containing format information. 

varArgs — Variableargument list. 

N umber of characters written or a negative value if there was an 
error. 

/* Pr ogr am VARGS, written 17 June 1 9 92 by 
Peter D. Hi pson */ 

#i n c I u d e <l i mi t s . h > 

#i nc I ude <st d a r g. h> 

#i nc I ude < s t d i o . h > 

#i n c I ude <s t d I i b . h > 

i nt Our Out put ( c har * Out put Buf f er , 



char * Ou t p u t Fo r ma t , 



v o i d 



ma i n ( ) 



char 



szBuff er[ 100]; 
nSum = 100; 



i nt 



( vo i d ) Ou r Out put ( sz Buf f er , 

" %s - %d , %s \ n " , 

"First", n S u m, "Second"); 



pri ntf ("%s", szBuffer); 



i nt 



OurOut put ( 
char * OutputBuffer, 
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char * OutputFormat, 



Note: 



{ 

v a _ I i st Arguments; 

va_start(Arguments, OutputFormat); 

vspri ntf ( Out putBuff er , OutputFormat 
Ar g u men t s ) ; 

va_end(Arguments); 

r et u r n ( 0 ) ; 

} 

See v f p r i ntf ( ) and vpr i ntf ( ) . 



wcstombsO 

H eader: 
Syntax: 

Description: 

Parameters: 



Returns: 
Example: 

Note: 



stdlib.h 

size_t wc s t o mbs ( c h a r * szDesti nation, 

const wc h a r _ t * pWideChars, 
size_t nSize); 

Converts the wide characters in the buffer pointed to by 
pwi dechars to m u Iti byte characters. Stores u p to n s i ze characters 

in s z De s t i n a t i o n . 

szDest i nat i on — Pointer to a buffer to receive the multibyte 
characters. 

pwi decharacters — Pointer to a buffer containing the wide 
characters to be converted. 

n Co u n t — Size of s z De s t i n a t i on. 
N umber of characters converted. 

wc s t o mbs ( s z B uf f e r , szWideChars, 
sizeof(szBuffer)); 

See wet o mb( ) . 
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wctombf) 

Header: stdlib.h 

Syntax: int wet omb( char * s z De s t i n a t i o n , const wc h a r _ t 

Wi deChar ) ; 

Description: Converts a single wide character in the buffer pointed to by 
pwi dechars to a multibyte character. 

Parameters: szDesti nation — Pointer to a buffer to receive the multibyte 
characters. 

wi dechar — Widecharacterto be converted. 
Returns: N umber of bytes resulting from the conversion. 

Example: wet omb( s z Buf f er, s z Wi d eC h a r [ 0 ] ) ; 

Note: Seewcst ombs ( i . 



printf() Format Codes 

The pri ntf ( ) family Of functions— pri ntf O , f pri ntf O , spri ntf () , vpri ntf() , 

vf pr i ntf ( i , and vspr i ntf ( i — uses a format string to describe the format of the 
output. T his format string enables the programmer to specify what is output. 

Theformatstringspecifiesthevariablesandhowtheyareoutput. Becausethese 
functions use a variable number of arguments, the function doesn't know what 
variables have been passed except to look at theformat string. M akingan error in one 
variable's type often causes problems with the variables that follow. 

H ow i sa vari abl ef orm atted ?T hefirst ch aracter i n a f orm at sped f i er i s a percent 
sign, %. This format specifier has the following fields: 

%[fl ags] [ si ze] [ . preci si on] [ prefi x] type 

T he f i a g s field is optional. Four values are allowed in this field, as shown in 
Table 14.8. 
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Table 14.8. Flags used with printfO family of functions. 
Flag character Description 

Left justify the output field within the width defined. 

' +■ Signed, positive values are always prefixed with a plus 

sign. Negative values are prefixed with a minus sign. 

' ' Signed, positive values are always prefixed with a blank. 

Negative values are prefixed with a negative sign. 

' #■ Alternate conversion adds a leading zero for octal values, 

a 'Ox' or 'OX' for hexadecimal values, forces a floating 
point number to always have a decimal point, and 
removes floating point trailing zeros. 



Thefollowingsectiondescribeseachtype ofpri ntto field, and themeanings 
for si ze, . preci si on, and pref i x fields. Becauseall these fields depend on the type 
field, thetable is organized with subheads for each type. 



C 

Thee type tells pri ntto to output a single character. This field is affected by the 
following: 

flags 

Only the- (left justify) flag is used. If the width field specifies a width greater than 
one, then the character can be either right justified (default) or left justified (using 
the left justify flag). 

width 

Specifies the width of the output. 
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.precision 

Ignored if present, 
prefix 

Ignored if present. 

dandi 

Thed andi typetdlspri ntfo to outputasigned decimal integer. Thisfield isaffected 
by the following: 

flags 

All flags as shown in Table 14.8 affect afield of thistype. 

width 

Specifies the minimum width. If the formatted result is less than thewidth, then it is 
padded with blanks. If the formatted result is greater than thewidth, then thewidth 
is ignored, and the formatted output's actual width is used. 

.precision 

Theprecision specifies theminimum number of digits to appear. This causes output 
that has fewer than the number of digits of width to be padded on the left with zeros. 

prefix 

The prefix allows specification of a short or long integer. U se h to specify a short 
(16-bit) integer, and i to specify a long (32-bit) integer. Thedefault isto thedefault 
size for an integer for the system. 

eandE 

Thee and e types tdl pri ntf ( ) to output a floating point number, using an expo- 
nential format. This output takes the form of [ ■ ] d. dddei +| ■ ] ddd. If the e type 
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is specified, then the form taken isi ■ ] d. d d d e [ +| - ] d d d with an uppercase E used to 
indicate theexponent. 

This field is affected by the following: 

flags 

All f i ags as shown in Table 14.8 affect a field of thistype. 

width 

Specifies theminimum width. If the formatted result is less than thewidth, then it is 
padded with blanks. If the formatted result is greater than thewidth, then thewidth 
is ignored and the formatted output's actual width is used. 

.precision 

Specifies the number of digits that follow the decimal point in the mantissa. 

prefix 

Two prefixes are recognized. The i prefix specifies the value is a doubi e. The l 
prefix specifies the value is a i ong doubi e. When an oat is passed as a parameter, it 
is always passed as a doubi e (unless it is cast as a float, which is not recommended). 

f 

Thef typetellspri ntf ( ) to output afloating point number. This field isaffected by 
thefollowing: 

flags 

All f i ags as shown in Table 14.8 affect a field of thistype. 

width 

Specifies theminimum width. If the formatted result is less than thewidth, then it is 
padded with blanks. If the formatted result is greater than thewidth, then thewidth 
is ignored and the formatted output's actual width is used. 
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.precision 

Specifies the number of digits that follow the decimal point. 

prefix 

Two prefixes are recognized. The i prefix specifies the value is a d o u b i e. Thei. prefix 
specifiesthevalueisai ong do u b i e . W hen at i oat ispassed asa parameter, itisalways 
passed as a d o u b i e (unless it is cast as a float, which is not recommended). 

gandG 

Theg and g types tell pri ntf ( ) to output using either thef , e, or e types, depending 
on the value of the argument. Thee type is used if the exponent for the conversion 
would belessthan -4 or greater than theprecision. T railing zeros are removed, and the 
decimal point appears only if there is a decimal part of the number. See thef , e, or e 
types for more information. 

n 

T he n type tells p r i n t f ( ) to save the current number of characters written so far to 
the variable pointed to by the argument. N o modifiers are allowed with then type. 

0 

Theo type tells p r i ntfo to output a decimal number in octal (base 8) format. This 
field is affected by thefollowing: 

flags 

All flags as shown in Table 14.8 affect afield of thistype. 

width 

Specifies the minimum width. If the formatted result is less than thewidth, then it is 
padded with blanks. If the formatted result is greater than thewidth, then thewidth 
is ignored, and the formatted output's actual width is used. 
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.precision 

T he precision specifies the minimum number of digits to appear. This causes output 
that has fewer than thenumber of digits of width to be padded on the I eft with zeros. 

prefix 

T he prefix allows specification of a short or long integer. U se h to specify a short (16- 
bit) integer and i to specify a long (32-bit) integer. T he default is to the default size 
for an integer for the system. 

p and P 

The p and p types tell pri ntf ( ) to output a pointer. The pointer is printed in 
hexadecimal notation, in aformat that may be machine dependent. The case of the 
typeisused to specify the case of the hexadecimal digits. This field is affected by the 
following: 

flags 

All f i ags as shown in Table 14.8 affect a field of thistype. 

width 

Specifies theminimum width. If the formatted result is less than thewidth, then it is 
padded with blanks. If the formatted result is greater than the width, then the 
width is ignored, and the formatted output's actual width is used. 

.precision 

The precision specifies the minimum number of digits to appear. This causes out- 
put that has fewer than the number of digits of width to be padded on the left 
with zeros. 

prefix 

With compilers that have segmented memory (and memory models) the prefix allows 
specification of near or far pointers. U se f to specify a far (or long) pointer and n to 
specify a near (or short) pointer. The default is to the default pointer type for the 
program. 
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S 

Thes type tells p r i ntf o to output a string. This field i s affected by thefollowing: 

flags 

All f i ags as shown in Table 14.8 affect afield of this type except for the + (for plus 
sign) and the' ' (a blank, again for signs). 

width 

The width specifier defines the minimum width. If the string is longer than the 
width and no . preci si on value is specified, then the output expands to the size of 
the string. 

.precision 

Specifies the maximum number of characters to be output. If the string being 
printed is larger than thewi dt h specification, then it will be truncated to. preci si on 
size. 

prefix 

W ith compilers that have segmented memory (and memory models) theprefix allows 
specification of a near or far pointer. U se f to specify a far (or long) pointer and n 
to specify a near (or short) pointer. The default is to the default pointer type for 
the program. 

U 

Theu typetellspr i ntf ( ) to output an unsigned decimal integer. Thisfield isaffected 
by thefollowing: 

flags 

All f i ags as shown in Table 14.8 affect afield of this type, except there can never be 
a minussign. 
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width 

Specifies theminimum width. If the formatted result is less than thewidth, then it is 
padded with blanks. If the formatted result is greater than thewidth, then thewidth 
is ignored and the formatted output's actual width is used. 

.precision 

T he precision specifies the minimum number of digits to appear. This causes output 
that has fewer than thenumber of digits of width to be padded on the I eft with zeros. 

prefix 

T he prefix allows specification of a short or long integer. U se h to specify a short (16- 
bit) integer and i to specify a long (32-bit) integer. T he default is to the default size 
for an integer for the system. 

x and X 

Thex andx typestell pri ntf ( ) to output an unsigned, hexadecimal integer. The case 
ofthehexadecimal digitsmatchesthecaseofthetype field. Thisfield isaffected by the 
following: 

flags 

All f i ags as shown in Table 14.8 affect a field of thistype. 

width 

Specifies theminimum width. If the formatted result is less than thewidth, then it is 
padded with blanks. If the formatted result is greater than thewidth, then thewidth 
is ignored and the formatted output's actual width is used. 

.precision 

T he precision specifies the minimum number of digits to appear. This causes output 
that has fewer than thenumber of digits of width to be padded on the I eft with zeros. 
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prefix 

T he prefix allows specification of a short or long integer. U se h to specify a short (16- 
bit) integer and i to specify a long (32-bit) integer. The default is to the default size 
for an integer for the system. 

scanf() format codes 

These a nf ( ) family of functions— scanf ( ) , f scanf ( ) , and sscanf ( ) — uses a 
format string to describe the format of the input. This format string allows the 
programmer to specify what is read. All arguments passed to these functions that are 
to receive values are passed as addresses. Failure to provide addresses causes the 
program to fail. 

The format string specifies what the variables will be when they are filled in, 
their types, and the format of the input data. Because these functions use a variable 
number of arguments, the function doesn't know what variables have been passed 
except to look at the form at string. 

H ow i sa vari abl ef orm atted ?T hefirst ch aracter i n a f orm at sped f i er i s a percent 
sign, %. This format specifier has the following fields: 

%[ * ] [ wi d t h] [ t y pel engt h] t y pe 

The* specifies that the next field oft ype isto beskipped. Thespecification of 
type i s i m portan t to ensurethefidd is correctly ski pped . 

T he optional specification width specifies the maximum width that is scan- 
ned for this fidd. The field may wdl be shorter than wi dt h, depending on the type 
specification. 

The t ype i engt h specifier provides information about the size of the object 
that recdves the input. Using an V character specifies a short (16-bit) object while 
the 'i ' character specifies a long (32-bit) object. When used with floating point 
arguments, the 'i 'character specifies a long doubi e object (its size bang implementa- 
tion dependent). 
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C 

Thee type tells scanf ( i to input one (or more) characters, which may include 
whitespace characters (the s type does not include whitespace characters). This field 
is affected by the following: 

width 

Specifies thewidth of theinput field. If not specified, then thewidth isassumed to be 
one character. 

typelength 

None allowed. 

d 

Thed typetellsscanf ( i to input a signed decimal integer. Thisfield is affected by the 
following: 

width 

Specifies the maximum width. 

typelength 

The typei ength specifier provides information about the size of the object that 
receives the input. U sing an 'h ' character specifies a short (16-bit) object while the 
'i ' character specifies a long (32 bit) object. 

0 

Theo typetellsscanf! ) to input a decimal number in octal (base8) format. Thisfield 
is affected by the following: 
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width 

Specifies the maximum width. 

typelength 

T he t y p e i e n g t h specifier provides i nformation about the size of the object that will 
receive theinput. Using an V character specifies a short (16-bit) object whilethe'i ' 
character specifies a long (32-bit) object. 

X 

Thex type tells sea nf ( i to input an unsigned, hexadecimal integer. This field is 
affected by thefollowing: 

width 

Specifies the maximum width. 

typelength 

Thet ypei engt h specifier provides information about the size of the object that re- 
ceives the input. Using an ■ it character specifies a short (16-bit) object, while 
the ' i ■ character specifies a long (32-bit) object. 

i 

Thei typetdlsscanf ( ) to input a signed decimal integer, which may bein a decimal, 
octal, or hexadecimal format. The first characters in the string are examined, and if 
they are ox, thenthenumberisassumedtobebasehexadecimal. If there is a leading 
o with no following x, then the base is assumed to be octal. If the leading character is 
not a o, then the number is assumed to be decimal. This field is affected by the 
following: 

width 

Specifies the maximum width. 
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typelength 

Thet ypei engt h specifier provides information about the size of the object that re- 
ceives the input. U sing an 'h ' character specifies a short (16-bit) object, while the 
'i ' character specifies a long (32-bit) object. 

U 

Theu typetellsscanf ( ) to input an unsigned decimal integer. Thisfidd is affected by 
thefollowing: 

width 

Specifies the maximum width. 

typelength 

T het y p e i e n g t h specifier providesinformation aboutthesizeof theobject that receives 
theinput. U sing an 'h ' character specifiesa short (16-bit) object, whilethe'i ' character 
specifies a long (32-bit) object. 

e, f, and g 

Thee, f , and g types tell scant ( ) to input a floating point number. 
This field is affected by thefollowing: 

width 

Specifies the maximum width. 

typelength 

With floating point arguments, the 'i ' character specifies a long double object (its 
size being implementation dependent). 
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n 

Then type tells s c anf ( i to save the current number of characters scanned so far to 
the variable pointed to by the argument. N o modifiers are allowed with then type. 

P 

Thep and p types tell scanf ( ) to input a pointer. The pointer is scanned in hexa- 
decimal notation, in a format that may be machine dependent. This field is affected 
by thefollowing: 

width 

Specifies the maximum width. 

typelength 

Notypeiength specifier is used. 
S 

Thes type tells scant o to input a character string, which consists of a group of 
nonwhitespace characters. Input is assigned up to thefirst whitespacecharacter. This 
field is affected by thefollowing: 

width 

Specifies the maximum width. 

typelength 

Notypeiength specifier is used. 
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[...] 

Thei . . . ] type tells s ca nf ( ) to input a character string, consisting of all characters 
thatarefound in thebrackets. Prefixingthecharacterswith a* causesall charactersthat 
are not in the group to be read. 

Typically, this input format is used to read strings that contain blanks or other 
whitespace characters. This field i s affected by thefollowing: 

width 

Specifies the maximum width. 

typelength 

No typei engt h specifier is used. 

Summary 

This chapter covered thevariousAN SI standard library functions: 

• The functions are prototyped in thestandard header files. 

• Programmers must be careful to pass the correct parameters to those functions 
that take a variable number of arguments (such aspri ntto ) because the 
compiler cannot check argument types 

• About 150 non-AN SI functions are available with many compilers. Using the 
non-ANSI function may create problems when the program is ported to a 
different compiler. 
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To help you gain a better understanding of how a C compiler produces the object 
module, this chapter looks at the process of compiling. M ost compilers take the 
following steps, in this order: 

1. Preprocess the input file, in this order: 

a. Process the ^preprocessor directives. 

b. Strip comments from the source (as necessary). 

c. Expand all macros. 

2. The syntax checker processes the file to check for syntax errors. 

3. The code generator generates the necessary object module. 

All preprocessor commands begin with a pound symbol (#). 1 1 must bethefirst 
nonblank character, and for readability, a preprocessor directive should begin in 
column 1. N oticethat a defined identifier is always a macro and can bereferred toin 
that way. 
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The C preprocessor offers four operators to help you in creating macros (see the 
section "The#define Directive") and the #i f series of directives. 



The Macro Continuation Operator (\ ) 

A macro usually must becontained on a singlelineThemacro continuation operator 
is used to continue a macro that is too long for a single line. When you are breaking 
a macro over several lines, usethemacro continuation operator asthelast character in 
thelineto be continued. H ere'san exampleof a multiline macro: 

#def i ne P R I N T MS G ( operand) \ 

pr i nt f ( #oper and " = %d\n", operand) 

This line is exactly equivalent to the following: 

tdefine PRINT MS G( operand) printf(#operand " = %d\n", operand) 

Themacro continuation operator allows your macros to be read and formatted 
more easily. 1 1 doesn't affect the operation of the macro. 

The Stringize Operator (#) 

T he stringize operator is used in creating a macro. 1 1 takes the particular operand to 
the macro and converts it to a string. To see how this works, look at this example: 

tdefine PRINT MS G( operand) printf(#operand " = %d\n", operand) 

When an integer variable (n count ) is being used as a counter, for example, you 
might use the statement to display ncount 's value for debugging: 

PRI NTMSG( nCount + 1) ; 

This statement then is expanded by the preprocessor to create the following 
source line: 

pri ntf("nCount + 1 " " = %d \ n " , n C o u n t + 1 ) ; 

This sample line of code shows that the variable's name has been included 
(using string literal concatenation) as part of the format string that pri nt f ( ) uses. 
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T hestringize operator causes the particular operand to a macro to beconverted 
to a string, by taking the literal characters of the operand and enclosing them within 
double quotes. 

TheCharacterizeOperator (#@) 

The characterize operator, which works much like the stringize operator, is used in 
creating a macro. It takes a particular single character operand to the macro and 
converts it to a character literal, by surrounding it with singlequotes. To see how this 
works, look at thefollowing example: 

tdefine MA K E C HA R ( operand) #@o per and 

W hen you want to create a character literal, as part of a c a s e : statement, for 
example, you can usetheMAKECHAR macro: 

swi tch( nCount + 1 ) 

{ 

case MAKECHAFU A) : 
/ * Act i on f or capi t al A */ 

break; 
case MAKECHAFU B) : 
/ * Ac t i o n f o r c a p i t a I B */ 

break; 
default: 
break; 

} 

The first case statement then is expanded by the Pre- Processor to create the 
following: 

case 1 A 1 : 

In thissamplelineof code, theoperand has been surrounded by singlequotes, 
yielding a character literal. This example isn't the most useful for using the character- 
ize operator, but it gets the point across. 

The characterize operator causes the particular operand to a macro to be 
converted to a character literal, by taking the characters of theoperand and enclosing 
them within singlequotes. This operator fails if it is given a single quote character. 
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The Token Paste Operator (##) 

The token paste operator tells the preprocessor to paste, to the token on the other 
side, the operand that either precedes or follows it. For example, you might code a 
macro to print one of several variables that have meaningful names: 

#def i ne P R I NTCOUNTER( v a r i able) \ 

pri ntf( "counter %d is %d 11 , variable, n C o u n t e r #v a r i a b I e ) 

This macro definition can then beused in a program such asthefollowing: 

int nCounterl; 

int nCounter2; 

int nCounter3; 

int nCounter4; 

PRI NTCOUNTEFU 1) ; 

This call to the macro can be expanded to 

pri ntf( "vari abl e %d is %d " , 1 , nCounterl); 

You decide how to use this operator. It has many uses when you create macros 
to help debug programs that use structures heavily. 

The Defined Identifier Operator (defined!)) 

The def i ned( ) operator is used with the #i f and #e i i f preprocessor commands. 
Thisoperator returns a logical true(nonzero) valueif theidentifier used asits operand 
is currently defined and a logical false (zero) if the operand is not defined. 

The primary use for def i ned( ) is in testing two different identifiers to see 
whether they are defined. You can use nested #\ f def statements; using def i ned( ) , 
however, makes the code easier to understand. 
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The define Directive 

Thetdef i ne command defines macros. C 'smacroshelpyou create powerful function- 
ality. Macros can be defined with substitutable parameters or as simple identifiers. 
The simplest macro probably is the following: 

#d ef i n e TRUE 1 

This macro defines the identifier true that always has the numeric value of 1 
substituted for it. For example, thefollowing lines havea conditional statement (and 
some comments): 

tdefine TRUE 1 

/* Later in the program... */ 

if ( nOur Ti me == TRUE) 
{ / * Process our t i me . . . * / 
/* our time code is here. */ 

} 

After the preprocessor finishes, this simple bit of code then reads: 

if ( n Ou r Ti me == 1 ) 

{ 

} 

Thiscodefragmentshowsthatthepreprocessorhassubstitutedthenumberi for 
the identifier true. In this example, true is the simplest form of a macro— so simple 
that it usually is referred to as the definition of an identifier. A more complex macro 
might have one or more operands, which enable you to test and create different 
statements, such as MACROS (see Listing 15.1). 

Listing 15.1. MACROS. C. 

/* Program MACROS, written 23 June 1 9 9 2 by Peter D. Hipson */ 
/* A program that shows macros. */ 

#i nc I ude <st di o. h> 
#i nc I ude <s t d I i b . h > 

continues 
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Listing 15.1. continued 



* The DONOT HI NG identifier, although it is defined, is basically 

* a no-operation. An example of its use is shown in the body 

* of the program. Some programmers define DONOTHI NG as a 

* semicolon; doing so, however, can create problems and is 

* not recommended. 
*/ 

#def i ne DONOTHI NG 

/* 

* Both TRUE and FALSE, below, can be considered to be macros 

* that don't have any operands. When they are included in a 

* source line, they expand to their literal contents. 



'/ 



#def i ne TRUE 1 

#def i ne FALSE ( ! TRUE) 

/* 

* Now define some stock macros. Both Ml N ( ) and MAX() may be 

* included (in lowercase) in stdlib.h (with many C compilers); 

* I define them in uppercase, however, to remind me that they 

* are macros, subject to side effects. 

*/ 

#def i ne MAX( a, b) ( ( ( a) > ( b) ) ? ( a) : ( b) ) 
#def i ne Ml N( a, b) ( ( ( a) < ( b) ) ? ( a) : ( b) ) 



/' 



SWAP( ) is a neat little variable swapper that swaps the 
contents of two variables in-place without temporary storage. 
The only caution is that the variables must be of the same 
size (but can be of differing types if necessary). 

Notice SWAPU's use of braces around the expressions, in 
case the macro is invoked as a single line after an if() 
state me nt that has no braces itself. Failure to include 
the braces can lead to some strange problems with macros 
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* that have mo re than one state me nt included in them, such 

* as is the case wi t h SWAP( ) . 

*/ 

#def i ne SWAP( a, b ) { a A = b ; b A = a ; a A = b ; } 

/* 

* Notice that P R I NT A B ( ) uses the stringize operator to form 

* its for ma t string. This usage enables you to have a nice 

* printf() statement without having to do a lot of typing. 

*/ 

tdefine PRI NTAB( a , b) printf(#a" = %d "#b" = %d \n", a, b) 



i n t ma i n ( ) 



int nOurTime = FALSE; 

i n t n S u m; 

int a = 10; 

int b = 11; 



/* The DONOTHI NG identifier tells you that the for()'s statement(s) 
* have not been omi 1 1 ed: 

*/ 

for (nSum = 0; nSum == nOurTime; nSum+ + ) 
DONOTHI NG; 

if ( nOur Ti me == TRUE) 
{ / * Process our t i me . . . * / 
/* our time code is here. */ 

} 

P Rl NT A B ( a , b); 

continues 
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Listing 15.1. continued 

SWAP(a, b); 
P R I NTAB( a , b); 
r et ur n( FALSE) ; 

} 



Each of the macros in theM ACROS program is useful in a real program. The 
mino and max o macrosarethemostusefultome.TheswAP( i macro hasbeen around 
a long time. (I came across it when I was writing assembly code for main- 
frame computers.) It en ablestwovariablestobeswapped without using any temporary 
storage- a han dy tool if you are ei th er sh ort of m emory or can n ot al I ocate a tern porary 
variable because of context. 



T he terror Directive 

T he #e r r o r directive typically is used as part of an #i f type conditional preproces- 
sor statement. For example, if you include in M ACROS.C the #e r r or directive as 
shown in thefinal lineof this codefragment: 

/* Program MACROS, written 23 June 1 99 9 by Peter D. Hipson */ 

#i n c I u d e < s t d i o . h > 
#i n c I u d e <s t d I i b . h > 

terror "This is an error" 

This directive, when encountered by the compiler, prints on the compiler's st de r r 
stream a message similar to the following: 

D:\ADC\SOURCE\MACROS. C(6) : error C2189: terror : "This is an error" 

Noticethatthecompiler'serror message includes thesourcefile'snameand line 
number, and a compiler error message that includes thestring included in the#e r r o r 
directive. 
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The Include Directive 

The#i nc i ude directive tells the compiler to include a header file at the current point 
in the source file. H eader files generally don't contain actual executable statements, 
but rather contain #d ef i n e identifiers, function prototypes, and so on. 

When you are including a header file, delimit the operand using either double 
quotes or a <> pair surrounding the operand. 

The directive #i nc i ude ■ ourf i i e. h- causes the compiler to search for the 
header file first in the current directory and then in the directories specified in the 
include search order. 

T he directive #i n c i ude <o u r f i i e . h > causes the compiler to search for the 
header file in the directories specified in the i n c i ude search order. 

If the header file specified in the #i nci ude directive has a fully qualified path 
name, this path is used to find the header file. 

The If Directive 

T he #i f directive is a useful part of the preprocessor's directives. It enables you to 
conditionally include (and exclude) parts of your source code. Unlike the other 
preprocessor directives usually grouped at the beginning of a source file, the #i f 
directive may be found at any point in the source file. 

T he #i f directive is followed by a constant expression (which the preprocessor 
evaluates) and has several restrictions, including thefollowing: 

• Theexpression must evaluateto constants. A variable cannot be used in the 
#i f directive. 

• Theexpression must not uses i zeof ( ) , a cast, or enum constants. 

• Theexpression is evaluated mathematically; string compares do not work. 

T he #i f directive enables you to compile code conditionally based on factors 
such as which operating system your program will run under and the compiler's 
memory model. When the #i f directive is used, you can combinetheti f directive 
with either the #ei se or the#ei i f directives. 
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The block of source code affected by the #i f directive is ended with an #ei se, 
#ei i f , or #e n d i f directive. 

The #ifdef Directive 

Totest whether an identifier hasbeen defined, you can usethetifdef directive. The 
identifier to be tested can be one you create (using #def i ne) or a predefined ident- 
ifier created by the C compiler. 

You might use the #i f d ef directive to avoid creating problems with macro 
redefinitions or for specific macros being redefined with slightly different (but 
functionally identical) operands. 

Themost common usel havefortheti f directiveisto comment out largeblocks 
of code that may contain embedded comments. Because you cannot use a surround- 
ing comment with such a block of code, a simple workaround procedureisto use#i f 
as shown in this example: 

for (nSum = 0; nSum == nOurTime; nSum++) 
DONOTHI NG; 

#ifdef DONOT COMP I L E /* Never compile this code */ 

if ( nOur Ti me == TRUE) 
{ / * Process our t i me . . . * / 
/* our time code is here. */ 

} 

#e n d i f / * DONOTCOMP I LE */ 
P R I NTAB( a , b); 

N oticethatthei f ( ) block of code (with its comments) has been removed using 
an #ifdef/#endif directive pair. I makesurethat theidentifier donotcomp i l e neveris 
defined. You can choose to use a different identifier; donotcomp i le, however, is 
descriptive. 

A second use of the#i f d ef directiveisto enableyou to undefinean identifier if 
you know that you will redefine it. 
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#ifdef SWAP 
#u nd ef SWAP 
#e n d i f 

#def i ne SWAP( a, b) {a A = b; b A = a; a A = b; } 

In this code fragment, you want to define a macro called swapi ) ; however, you 
want to avoid any problems in redefining an existing swapi ) macro. This code is 
necessary to avoid an error message if swapi ) already exists and then is redefined. 

T he #ifndef Directive 

Totest whether an identifier hasnot been defined, you can usetheti f ndef directive. 
The identifier to be tested can be one you create (using #d ef i n e ) or a predefined 
identifier created by the C compiler. If the identifier has not been defined, the 
statements following the #i f n d ef directive are executed until either a #en d i f , #ei i f , 
or #e i s e is encountered. 

Anexampleof the#i f n d ef directiveisthecodeused to prevent aheaderfilethat 
isincluded twicefrom creating problemswith macro redefinitions. An exampleof the 
useof #i f n d ef to prevent problems with multiple inclusion of a header file is shown 
inthefollowingcodefragment.Thiscodefragmentassumesthattheheaderfile'sname 
isOURHEAD.H. 

#ifndef OURHEAD 

/* The include file's lines are here... */ 

#def i ne _ OURHEAD 

#e n d i f / * _ OURHEAD */ 

N otice that the first time the header file is included, the identifier ourhead 
will not have been defined, and the test will succeed. The lines for the header file 
are processed and the final line defines the identifier ourhead. If this header file is 
included a second time, theidentifier ourhead then isdefined, and thetestfails The 
lines for the header file are ignored. 

A second useof the #i f n d ef directive is to enableyou to definean identifier if 
it hasnot been defined yet. I n thefollowing classic example, theim l identifier (which 
is in a number of header files) isdefined. 
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#i f n d e f NULL 

#def i ne NULL ( i nt *) 0 

#e n d i f 

In thiscodefragment, besurethat theNUL l identifier is defined. If it is defined, 
you accept the definition; if it is not defined, you define it. This code is necessary to 
avoid an error message if null already exists and then is redefined. 

The #else Directive 

Like the C language's i f ( ) statement, the preprocessor has an i u ei se construct. 
Often, you must use either one block of codeor another depending on theresultsof 
a given test. You can maketwo separates f tests, each having the opposite effect; this 
technique, however, createscodethatisgenerallyunreadableand difficult to maintain. 
(You might change one #i f and forget to update the other.) 

Typically, #ei se is used when you need to use one block of source code (which 
can includeother preprocessor directives), or another, but never both. An exampleof 
the #e i se is shown in the following code fragment: 

#i f def i n e d ( VERSI ONI) 

/* Lines for the first version. */ 

#el se /* it's not VERSI ONI */ 

/* Lines for the other versions. */ 

#endi f / * VERSI ONI t est i ng */ 

Thesamecodewritten withoutthetei se ismorecomplexand moredifficultto 
understand: 

#i f def i ned( VERSI ONI) 

/* Lines for the first version. */ 

#e n d i f / * Not VERSI ONI */ 

#i f I def i n ed ( VERSI ONI) 

/* Lines for the other versions. */ 

#e n d i f / * Not VERSI ONI */ 

Using #eise when it's needed can make your preprocessor code more 
manageable. 
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The M if Directive 



To make the creation of nested testing using preprocessor directives easier, AN SI C 
has introduced the #ei i f directive. It follows an #i f (or another #e i if) directive, 
effectively ending the#i f (or #e i i f )'sblock and introducing a new conditional block. 

Typically, #ei i f is used where you need multiple tests, for example, to test for 
two or more versions of a compiler. An example of the #ei i f is shown in the 
following code fragment: 

#i f def i n ed ( VERSI ONI) 

/* Lines for the first version. */ 

#el i f def i n e d ( VERSI 0N2) 

/* Lines for the second version. */ 

#el i f def i n e d ( VERSI 0N3) 

/* Lines for the third version. */ 

#e n d i f / * VERSI ON? */ 

Thesamecode written without the#e i i f ismorecomplexand moredifficultto 
understand: 

#i f def i n ed ( VERSI ONI) 

/* Lines for the first version. */ 

#e I s e / * Not VERSI ONI */ 

#i f def i n ed ( VERSI 0N2) 

/* Lines for the second version. */ 

#el se / * Not VERSI 0N2 */ 

#i f def i n ed ( VERSI 0N3) 

/* Lines for the third version. */ 

#endi f / * VERSI 0N3 */ 

#endi f / * VERSI 0N2 */ 

#endi f / * VERSI ONI */ 

Using #eiif when it's needed can make your preprocessor code more 
manageable. 




The#endif di rective ends the nearest #i f preceding it. Every #i f requires an #e n d i f 
statement; #eise and #eiif directives, however, do not require separate #endi f 
statements. 
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The following code fragment shows nesting of conditional preprocessor state- 
ments and the effect of the #endi f statements. Notice how the comments following 
the #e n d i f directives make the code easier to read and modify. Try to get into the 
practice of commenting your preprocessor directives just as you would comment 
your regular C source code. 

#ifdef DLL /* Creating a Dynamic Link Library */ 
# i f n d e f MT /* DLLs must be multitasking */ 
/* Error message for this condition! */ 
terror "Cannot define DLL without MT" 
#el se 

/* whatever is reguired for a DLL */ 
#endi f / * MT */ 
#endi f / * DLL */ 

Using nested conditional preprocessor directives enables you to make 
complex decisions about what is being done with the program. Your program 
(commonly) might have three versions: a low-priced entry version, a higher-priced 
full-featured version, and a freebie demo version. Using #i f directives enables you to 
maintain onesetof sourcecodethat compiles differently depending on which version 
of the program is being created. 

The #line Directive 

By using the #i i ne directive, you can change either the current line number (which 
then is successively incremented for following lines) or, optionally, the filename 
associated with thecurrent source file. 

W hen you areusing an integrated debugger, which checkstheerror and warning 
messages produced bythecompiler, changing thelineorfilenamecan produce results 
that may not be what you expect. W hen you are using #i i n e , make sure that you 
understand what its effects will be in your environment. 

Thecurrent linenumber isalwaysavailablein thepredefined identifier l i ne 

, and thecurrent filenameisavailablein thepredefined identifier fi le . Both 

of theseidentifiersareused with thea s s e r t ( ) macro, and you can createerror message 
substitutions using them. Let's look at an example of using the #i i ne directive. 
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/ * Source file is OURFI LE. C */ 

pri ntf( "Thi s file is 1 %s 1 the line is 1 %d 1 \ n " , _ _ F I L E 
LI N E _ J ; 

#1 i ne 1 0 0 0 0 " DEBUGI T. C M 

pri ntf( "Thi s file is 1 %s 1 the line is 1 %d 1 \ n " , _ _ F I L E 
..LINE _ J ; 

H ere are the results of running this program fragment: 

This file is 1 OURFI LE. C the line is 1 3' 
This file is 1 DEBUGI T. C the line is 1 1 00 0 2' 

The#i i ne directivecan beuseful when your sourcefilesdon'thavemeaningful 
names and renaming them is not practical. 

T he #pragma Directive 

The#pragma directive is, by AN SI standards, implementation-defined. Itisusedto 
issuespecial commandstothecompiler, using a standardized method. Do not assume 
that any specific operand with #p r a g ma ispresent when usingagiven compiler.Two 
pragmas are relatively common— message and pack. Your compiler probably offers 
several other pragmas in addition to these two. 

The message Pragma 

The message pragma enables you to write a message to stderr while the file is 
compiling. When you aredebugging, check to see which identifiers aredefined. The 
following code fragment has a message indicating which of the three versions of the 
program is being compiled: 

#i f def i ned( VERSI ONI) 

#p r a g ma message "The first version." 

#el i f def i n e d ( VERSI ON2) 

fpragma message "The second version." 

#el i f def i n e d ( VERSI ON3) 

fpragma message "The third version." 

#e n d i f / * VERSI ON? */ 
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The pack Pragma 

The pack pragma enables you to control the packing of structure members. This 
pragma usu ally isused with a parameter; used withouta parameter, however, it restores 
the default packing value. Figure 15.1 shows an example of the effects of packing 
structures. This packing, called data alignment, affects the way each element in a 
structure is stored. 



(pack 1-byte alignment) 



(pack word alignment) 




struct _OurStruct { 
char szState[3] 
int nCode; 
char szZip[5] 
float fProf 
} OurStruct 



Notice that with 
byte alignment 
each object can 
be aligned with 
either an even 
or odd byte 
making the object 
smaller . 




10 Notice that with 

11 word alignment 

12 each object is 

13 aligned with an 

14 even byte, 



15 allowing 



faster access . 



Figure 15.1. The effect of packing and the pack pragma. 



All computersmost efficiently access objects aligned on boundariesthatareeven 
multiples of the memory bus width. For an 80286 C PU , which accesses memory in 
16-bit widths, accessing wordsthatarealigned to even bytes is optimal. For an 80386/ 
486— that is, a 32-bit processor that accesses memory in 32-bit widths— memory is 
accessed optimally using every other even address. T heeffectsof accessing data objects 
that arenot optimally aligned aredifficult to predict. 0 n onehand, aligning on a byte 
boundary makes the aggregate data objects smaller (and if they are used in arrays, the 
size difference can be significant), and the speed of even alignment may also be 
significant for an object that is accessed often. 

M any programmersexperiment with alignmenttofind theoptimal compromise 
between size and speed. I usually usebytealignment for infrequently accessed objects 
and word alignment for objects that are accessed more frequently. 
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T he #undef Directive 

At times you might need to redefine a macro, often when an identifier has been 
defined outsideyour program and you areusing it for a different purpose. To remove 
a definition of a macro, you should use the #u n d ef directive. The following code 
segment shows how this directive is used: 

#i f def i n ed ( VERSI ONI) 
#u nd ef VERSI ONI 
#e n d i f 

#def i ne VERSI ONI "The is Versi on 1. 0" 

Using #un def to remove a definition of a predefined macro is not a good idea. 

Predefined Macros 

ANSI C defines a number of macros. Although each one is available for your use in 
programming, the predefined macros should not be directly modified. 

The_ _DATE_ _M aero 

The date __macro contains the current date as a character literal in thefollowing 

format: 

" MMM DD YYYY" 

whereMMM is the three- character month abbreviation, in mixed case; dd isthecurrent 
day, padded with a blank if the day is less than 10; and yyyy istheyear. 

The__TIME__Macro 

The__Ti me __macro containsthecurrent timeas a character literal in thefollowing 
format: 

" HH: MM: SS" 

whereHH is hours, mm isminutes, and ss isseconds. 

If any of the three is less than 10, the field ispadded with aleading 0. 
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The_ _FILE_ Macro 

The. _fi le macro contains the current filename as a string literal. This macro's 
contents can be changed using the #i i ne directive. 



The_ _LINE_ Macro 

The_ line macro contains the current linenumber asa decimal constant. This 
macro's contents can be changed using the #i i ne directive. 



The_ _STDC_ Macro 

The. . st dc macro is defined asa decimal constant (valueof 1) when thecompiler 
complies with theANSI standard. 



NULL 

null is defined asa pointer guaranteed not to point to anything valid. This pointer 
often isusedasboth an initializing valueand an error return. You generally should use 
theNULL macro ratherthano whenyouareassigninganull pointertoapointervariable. 

null commonly is assigned to variables of other types; you mustbesure, how- 
ever, that the results are what are expected. You should not assume that null is the 
equivalent to zero (which is often defined as a macro called false), because this may 
not be the case. 



T he off setoff) Macro 

The of f set of ( ) macro returns the offset (in bytes) of a member of a structure from 
the beginning of the structure. 
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Summary 

In this chapter, you learned about the preprocessor's directives. 

• T he preprocessor directives enable you to control the compilation of the 
program and to optionally include or exclude parts of a program based on 
predefined identifiers. 

• Preprocessor directives can be in header files and in your source files. 

• All identifiers defined with the #d ef i ne directive are macros; a macro that has 
no parameters, however, often is referred to as simply a defined identifier. 

• AN SI standard C defines a number of macros that can be used in program- 
ming to assist in debugging and development of a program. 
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fficiency 

J ust because a program has been written does not mean that it works correctly or is 
efficient. This chapter looks at debugging a program and methods for making the 
program more efficient. 

Debugging 

1 1 i sa rareprogram that worksthefi rst ti me. M anyC programsarecomplex, containing 
thousandsof lines of code. Even iftheprogrammerhasnotmadeany syntax errors, the 
assumptions made when writing a program can create serious problems. 
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Debugging a program involves several steps: 

1. Correct all warnings and errors that the compiler finds. M any programmers 
assume that the default error level is enough. T his is incorrect— set the error 
level ashigh as possible. Correct all warnings and errors, or understand why 
you do not have to correct them. 

2. After the program compiles without warnings or errors, the real debugging 
takes place. Use the program and make sure that it performs as you expect. 
This process, called alpha testing, may take some time. The more problems you 
find and correct, however, thefewer the user will find. 

3. After finding and correcting problems during the alpha testing, find a few 
qualified users to test the program in an environment as close as possible to 
that which the program will be used in. This testing is called beta testing. M ake 
sure that the testers really use the program. Generally, beta testers get a free 
copy of the product for their effort. 

4. After beta testing, the product should be bug free. Any problems found by you 
(in alpha testing) and your test users (in beta testing) should be corrected. Beta 
testers often test two or three versions of the product. 

5. Now that the product is finished, you ship it. Remember the first customer's 
name, because this is the person who finds the first bug, usually within afew 
minutes of using the product. Find ways to minimize the bug's effect. After the 
product has been used for a few months, create an updated version that 
corrects all the bugs the users have discovered. 

The first part of debugging is finding the errors, the second part is correcting 
them, and thethird and fin al part i s en su ri n g th e correcti on does n ot create n ew errors. 



Common Bugs 

Following are some of the most common errors made when programming in C : 

• Using uninitialized variables 

• M isusing the assignment and equality operators 

• U nexpected side effects 

• M isuse of global variables 
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• M isuseof automatic variables 

• U sing variables of different sizes or types together 

• I ncorrect operator precedence 

• Not using the proper array bounds 

• M isusing pointers 

• Assuming the order of evaluation for function parameters 

• Assuming theorder of evaluation for operations where the order of evaluation 
is undefined 

Each of these errors is discussed in this section. 

Uninitialized Variables 

U singavariablethathasnot been initialized isaproblem when thevariableisafloating- 
point variable. Almost anything can happen, such as a trashed operating system, 
W indows programs that create U AEs, or 0 S/2 programs that do not work correctly. 

Misused Operators 

M isusing the assignment operator (=) and the equality (==) operator is another 
common bug. For example, the following f or ( ) loop will never end: 

f or ( i = 0; i = 1; i + + ) 

You will get a warning— assignment within conditional expression— but if you do 
not understand the warning message, you may think the compiler is referring to the 
initialization section (where i is initialized to 0) of thef or ( ) loop. The variable: is 
initialized toO, then it is assigned thevalueof 1 in the test section of thef or ( ) loop, 
then it is incremented attheend.Thenexttimearound, i is again set to 1, and soon. 
If the loop is tight (no calls to I/O functions or functions that may call DOS), it's 
power-switch time. 

I n the next example, the compiler does not return a warning: 

i == 20; 

This line of code compares i and 20, then throws away the result. If you don't look 
sharply, you'll spend a lot of time wondering why i is never set to 20. 
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Side Effects 

M ost macros can cause strange side effects. Consider the foil owing, where max( ) isa 
macro: 

i = max ( i ++, j ) ; 

if i and j are originally i , what isi on return?T ry it, and you will find that 
i is still 1. T hei variableisincremented afterthemaxi i macro is evaluated but before 
the result of the ma x ( ) macro is assigned to i . 

So, what is the result of the following? 

i = max ( + + i , j ) ; 

The result is not 2, but 3. The i variable is incremented when the comparison is 
performed, and because the variable is then 2, it isassigned to i . But there is a prefix 
increment on the assignment, so the variable is incremented again! 

Be careful when you use prefix and postfix increments and decrements with 
macros, or you may get different results than what you expect. 

Global Variables 

N ever use a global variable as a scratch variable. Even if you know that the global 
variable is not used elsewhere, you may choose to use it later, and then... When you 
ch an ge th e val u e assi gn ed to a gl obal vari abl e, th i n k about th e effects you r chan ge wi 1 1 
have on theother places where the vari able is used. 

Automatic Variables 

When a variable is defined inside a block and has not been declared with the static 
identifier, thevariable is called an automatic variable and exists only whilethe block 
is executing. 

Automatic variables do not retain their value between calls to the function. 
Automatic vari ablescannot bepassed back to thecallingfunction (thecompiler creates 
astatic variable to pass back if necessary). They are not initialized and therefore may 
contain unpredictable values. 
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Mixed Variable Sizes and Types 

Another common bug results when you use variables of different sizes or types 
together. You cannot successfully assign the u n s i g ned i nt u so met hi ng, which hasa 
val ue of 45000, to the s i gned i nt i ei se. The results are not right, becausei ei se will 
have a value of -20536. 

The same is true if you try to assign i Thi ng, which hasa value of 2345678, to 
i ei se. The result (-13619) isagain incorrect. Unlikesigned errors, size errors return 
a warning. 

Operator Precedence 

I have adopted a simple rule regarding operator precedence: When in doubt, use 
parentheses, lots of parentheses, because they override any other order of precedence. 

In thefollowing example: 

i nt i =3; 
i nt j =5; 

if ( i = ma x ( i , j ) == 5 ) 

1 isassigned to i .This istheTRUE condition becausemaxi i , j) is equal to 5. 
When the example is changed to thefollowing: 

i nt i =3; 
i nt j =5; 

if ( ( i = max ( i , j ) ) ==5) 

thecorrect value, 5, isassigned to i .Theparenthesesforcetheassignmenttooccurfirst, 
even though the conditional test normally has a higher order of precedence. 

When in doubt, use parentheses. Table 16.1 liststheoperatorprecedenceforC. 
When more than one operator belongs to the same group, they have the same 
precedence and are evaluated according to the rules of associativity. 
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Table 16.1. Operator precedence in C. 



0 perator 


Function 


Group 


Associativity 


I ) 


Function call 


1 


Left to right 


[ ] 


Array element 


1 


Left to right 




Structure or 
union member 


1 


Left to right 


- > 


Pointer to 
structure member 


1 


Left to right 


++ 


Postfix increment 


1 


Left to right 


— ■ 


Postfix decrement 


1 


Left to right 


: > 


Base operator 


1 


Left to right 


! 


Logical NOT 


2 


Right to left 




Bitwise complement 


2 


Right to left 




Arithmetic negation 


2 


Right to left 


+ 


Unary plus 


2 


Right to left 




Address 


2 


Right to left 


* 


Indirection 


2 


Right to left 


si zeof 


Size in bytes 


2 


Right to left 


++ 


Prefix increment 


2 


Right to left 


- ■ 


Prefix decrement 


2 


Right to left 


(type) 


Type cast 


3 


Right to left 


* 


M ultiplication 


4 


Left to right 


/ 


Division 


4 


Left to right 


% 


Remainder 


4 


Left to right 


+ 


Addition 


5 


Left to right 




Subtraction 


5 


Left to right 
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Operator 


Function 


Group 


Associativity 


<< 


Left shift 


6 


Left to right 


>> 


Right shift 


6 


Left to right 


< 


Less than 


7 


Left to right 


<= 


Less than or equal to 


7 


Left to right 


> 


Greater than 


7 


Left to right 


>= 


Greater than or equal to 


7 


Left to right 


== 


Equality 


8 


Left to right 


i = 


Inequality 


8 


Left to right 


& 


BitwiseAN D 


9 


Left to right 


A 


Bitwise exclusive 0 R 


10 


Left to right 


1 


Bitwise inclusive 0 R 


11 


Left to right 




Logical AN D* 


12 


Left to right 




Logical OR* 


13 


Left to right 


el?e2: e3 


Conditional* 


14 


Right to left 


_ 


Simple assignment 


15 


Right to left 


* = 


M ultiplication 
assignment 


15 


Right to left 


/ = 


Division assignment 


15 


Right to left 


%= 


M odulus assignment 


15 


Right to left 


+ = 


Addition assignment 


15 


Right to left 




Subtraction assignment 


15 


Right to left 


<< = 


Left-shift assignment 


15 


Right to left 


>> = 


Right-shift assignment 


15 


Right to left 


&= 


Bitwise-AN D assignment 


15 


Right to left 



continues 
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Table 16.1. continued 



0 perator 



Function 



Group 



Associativity 



Bitwise-exclusive-OR 
assignment 



15 



Right to left 



Bitwise-inclusive-OR 
assignment 



15 



Right to left 



Comma* 



16 



Left to right 



* Everything preceding the operator isevaluated before the operator isprocesed 

Not Using Proper Array Bounds 

Arrays always start at 0. For example, if i Array is defined as 

int i A r r a y [ 2 5 ] ; 

the first element isi Ar r ay[ 0] , and the last element is i a r r a y [ 24] . 
T he next example goes a step further: 

for ( i =1; i <= 25; i + + ) 
{ 

i A r r a y [ i ] =i; 

} 

Thisexamplefails, perhaps causing one of thosedifficult problems that takeso much 
timeto find and correct. The example assigned something to the26th element of an 
array that is defined with only 25 elements. Also, thefirst element is skipped because 
theforo loop starts at 1, not 0. 

A loop that correctly assigns all the elements of i Array follows: 

for ( i =0; i < 25; i + + ) 

{ 

i Ar r a y [ i ] = i ; 

} 
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Misused Pointers 

When you understand pointers, arrays, and indirection, you know you area real C 
programmer. Until that day, you will sometimes use them incorrectly. Pointers and 
indirection can cause major problems when functions are involved. 

If you do not feel comfortable with the concepts of pointers, thisisagood time 
to review C hapter 3, "Pointers and I ndirection." 

Order of Evaluation 

T heorder of evaluation for function parameters can not beguaranteed. T hefollowing 
code is unacceptable because you do not know when Your f unci ) will be evaluated: 

OurFunct(x = YourFuncU, x); 

Thesecond parameter, x, could be either the new valuefrom Your Fund ) or whatx 
contained before the call to Your f unci ) . 

The order of evaluation for some other operations is also undefined. For 
example, in the following code: 

i n t i =0; 

int n A r r a y [ 10] ; 

n A r r a y [ i ] = i ++; 

you cannot determine whether nArr ay[ o] or n Ar r ay[ n is assigned; it could be either 
one. To correct this, ANSI C defines sequence operators, which guarantee that the 
compiler has evaluated everything that must be evaluated at that point. 



Rulesfor Debugging 

When you debug a program, thefollowing rules will help you and perhaps save a bit 
of time: 

1. Assume nothing. Do not assume that a variable has the correct value, even if 
you see that the variable was assigned avalue. Print the variable's value at the 
time of thefailure. Someother part of the program may have trashed it. 

2. When the value of a variable changes to something unexpected, check the 
logical tests to see whether you have inadvertently assigned a value rather than 
tested it. 



649 



Part IV • Documenting the Differences 



3. Takea break. Byworkingon something else for a while, more often than not 
you will suddenly realize the cause of the original problem. 

4. If the bug is not in thesection of code you originally suspected, it issome- 
whereelse. Do not fall into thetrap of thinking, "Thebug can't bein this part 
of the code because I checked it." 

5. Correct all the compiler's warnings. Setthewarning level ashigh as possible. If 
you are writing Windows programs, usesTRi ct to assure the maximum 
checking. 

6. Pointers cause the most problems. Array-bound overwriting causes almost as 
many problems. Strings are arrays. In mostC compilers, nothing detects when 
a string's bounds are exceeded. I f the string is on the stack when its bounds are 
exceeded (because it is an auto variable), the program will probably do some 
strange things. 

7. Back up your disk. 0 ne of my first C programs promptly trashed my disk. T he 
only blessing was that I did not have a backup of the program that did the 
dirty work— it did itself in! 

8. From time to timethere are compiler bugs, but they arenot usually the reason 
your program fails. 

9. H ave another C programmer look at your code. 

10. When all else fails, rewrite the code so that it works differently. 

You arenot guaranteed a perfect program just becauseyou avoid thesecommon 
errors. The most common bugisthesimpleprogram logic bug. The program doesn't 
work thewayyou think it does. Theprogram issyntacticallycorrectand doesnot have 
any programming bugs, but its logic is incorrect. W ith a lot of work, a debugger, and 
patience, you can trace the program's execution. Eventually, you can find the spot 
where the results are not what you expected, and perhaps the bug. 



Using the assert!) Macro 

T he C language provides the programmer with an important feature, the a s s e r t ( ) 
macro. Thismacroenablesyou to makeaconditional test, then printsan error message 
and ends the program if the test fails. 
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Listing 16.1, ASSERT . C, showshow theasse r t ( ) macro is used. You must be 
careful and read the message correctly. N otethat assent ) activates when the test is 
false (fails). 

Listing 16.1. ASSERT. C. 

/* ASSERT, written 1 9 9 2 by Peter D. Hipson */ 
/* This program shows the assert!) macro. */ 

#i nc I ude <l i mi t s . h> 

#i nc I u d e <s t d a r g . h > 

# i n c I ude <st di o. h> 

# i n c I ude <s t d I i b . h > 

# i n c I ude <a s s er t . h > 

#def i ne TRUE 1 

#def i ne FALSE ( ! TRUE) 



void ma i n ( ) 



i n t n Va I u e = 1 ; 
char szBuf f er [ 2 5 6] ; 



whi I e (TRUE) 

{ 

p r i n t f ( " Enter anything but 25 to test the assert!) macro: "); 
gets(szBuffer); 

sscanf ( szBuf f er , "%d", &nValue); 
asser t ( nVal ue == 25) ; 

} 

} 
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Typical outputfromtheasserto macro follows: 

assert 

Enter anything but 2 5 to test the assert!) macro: 345 
Assertion failed: n V a I u e == 25, file assert. c, line 27 

abnormal program ter mi nation 

Thefilenameandthelinenumberareprovided; both ofthesecan bechanged with the 
#i i ne directive. 

When you have finished debugging a program, it is not necessary to comment 
out theasser t ( ) calls. Instead, you should define the nde bug identifier and simply 
recom pi I e the program . T he preprocessor stri ps out the a s s e r t ( ) cal I s for you . L ater, 
if you discover that the program still hasbugs, aquick recompilewithout defining the 
nde bug identifier will restore all your ass er t < ) calls. 

Debug Strings and Messages 

Writing lines to the screen, a communications port, the printer, or a file while a 
program is executing can beapowerful debugging tool. Because thistechniquedoes 
not require a debugger, it can be easy to implement. 

You can trace the entire program's execution using such a technique, but you 
must carefully plan your debugging session. Listing 16.2, D BG ST R N G.C, shows the 
use of a debugging output function. 

Listing 16.2. DBGSTRNG.C. 

/* DBGST RNG, written 1 9 9 2 by Peter D. Hipson */ 
/* This program has a debug output function */ 

#i n c I ud e <l i mi t s . h > 

#i nc I ude <st dar g. h> 

#i nc I ude <st di o. h> 

#i n c I ude <s t d I i b . h > 

#i n c I ude <as s e r t . h > 

#def i ne TRUE 1 

#def i ne FALSE ( ! TRUE) 
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#u n d e f DebugSt r i ng 
#ifdef NDEBUG 

tdefine DebugSt r i ng( exp, file, msg) ((void)O) 
#el se 

void __cdecl DebugStri ng( voi d *, FILE *, void *, void *, unsigned); 

tdefine DebugSt r i ng( exp, file, msg) \ 

( (exp) ? DebugStri ng(#exp, file, msg, _ F I L E _ _ , LI N E _ _ ) 
(void) 0) 

#endi f / * NDEBUG */ 



void ma i n ( ) 



i nt nVal ue = 1; 
char szBuffer [ 256] ; 



while ( n Va I u e ) 

{ 

DebugSt r i ng( nVal ue >= 15 && nValue <= 20, stderr, szBuffer); 

pri ntf( "Enter 10 to 25 for message, 0 to end loop: "); 
gets(szBuffer); 

s s c a nf ( s z Buf f er , " %d " , &nVa I ue) ; 

DebugSt r i ng( nVal ue >= 10 && nValue <= 25, stderr, szBuffer); 

} 

} 



void _ _cdecl DebugSt r i ng( 
void * s z Tes t , 
FILE * File, 
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void * szMessage, 
void * szFile, 
unsigned nLine) 



{ 



f pr i n t f ( F i I e , 

"\ n' %s' MSG ' %s' IN ' %s' LINE ' %d ' \ n" , 

szTest , 

szMessage, 

s z Fi I e, 

nLine); 



For example, using the _ Deb ugst r i ng( ) function to debug a program run 
produces thefollowing typical run of D BGSTRN G.C: 

dbgst rng 

Enter 10 to 2 5 for message, 0 to end loop: 10 

'nValue >= 10 && nValue <= 25' MSG '10' IN 'dbgstrng.c' LINE '48' 

Enter 10 to 25 for message, 0 to end loop: 1 

Enter 10 to 25 for message, 0 to end loop: 14 

'nValue >= 10 && nValue <= 25' MSG '14' IN 'dbgstrng.c' LINE '48' 

Enter 10 to 25 for message, 0 to end loop: 15 

'nValue >= 10 && nValue <= 25' MSG '15' IN 'dbgstrng.c' LINE '48' 

'nValue >= 15 && nValue <= 20' MSG '15' IN 'dbgstrng.c' LINE '41' 
Enter 10 to 25 for message, 0 to end loop: 19 

'nValue >= 10 && nValue <= 25' MSG '19' IN 'dbgstrng.c' LINE '48' 

'nValue >= 15 && nValue <= 20' MSG '19' IN 'dbgstrng.c' LINE '41' 
Enter 10 to 25 for message, 0 to end loop: 0 

When using afunction such asDebugst r i ng( ) , you arenot restricted to using 
stderr. Instead, you might open a communications port or the printer as the 
debugging fileor writetheoutputtoafile. When writing to a file, be sure you flush 
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thefile's buffer after each write. Otherwise, you could losethemost important part of 
theprogram'soutput if theprogramfailswithout closing thefileor flushing thebuffer. 

When programming under Windows, you could call out put Debugst r i ng( ) 
rather than f pr i ntf ( ) . The out put Debugstr i ng( i Windows function writes a string 
to the debugging terminal (or whatever destination you choose if you usetheDBwi n 
program), without halting the program or destroying the contents of the Window's 
screen. 



Debuggers 

Every compiler comes with a debugger. Regardless of the environment (DOS, 
Windows, OS/2, or UNIX), the concept behind the use of a debugger is the same: 
to allow accesstovariouscommandswhiletheprogram runsso that you can monitor 
its execution. 

Typical services offered by most debuggers follow: 

• Execution in an environment similar to thetypical operating environment. 
This involves using as little memory as possible (a requirement that was 
difficult with D 0 S on a PC , but is easier with the rapid acceptance of 
protected-mode operating systems such as Windows and OS/2) and not 
interfering with the output device (the screen). To avoid interfering with the 
screen, the debugger generally uses a serial terminal, a second monitor (often a 
monochrome adapter, or M DA), or two workstations (with network- based 
debugging). 

• M emory examination. This includes simple memory dumps, examination of 
external variables (by name), and examination of local variables. 

• M emory modification. This generally is limited to changing variables, both 
global and local. 

• Program breakpoints. At a program breakpoint (a specified point of interrup- 
tion), the debugger is given control before thelineor instruction isexecuted. 
At a breakpoint, you might examine variables, registers, or memory. 

• Memory breakpoints. These are similar to program breakpoints, but the 
memory specified need not bean instruction. For example, the breakpoint 
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could be at a data object. M emory breakpoints are useful if you want to 
determine what part of the code is modifying a variable. You could specify a 
value at the given location, and when thevalue is stored there, the breakpoint 
is entered. 

• Program modification. Some debuggers enable you to correct minor errors, 
then continue program execution. This feature is useful for programs with 
complex setup or initialization processes. 

• Execution stepping. Almost all debuggers can execute statements one line at a 
time. This technique, called stepping, enables you to trace theflow of the 
program (for example, the number of times the loop executed, and thefunc- 
tionsand subroutines that were called). Some debuggers enable you to tracein 
both the high-level language (such asC) and assembly (or machine) language. 
Tracing the program's flow in C is often thefastest and most valuable option 
because you can see the effects of each program statement. 

When using a debugger, you mustbalancethelearningcurve(thatis, how long 
it takes you to learn to use the debugger), the amount of time needed to set up the 
program and the debugger, and how quickly you can find the problem. 

I n C programming on thePC , each compiler hasitsown debugger. T herearealso 
anumberof stand-alonedebuggers, most of which require additional hardware(plug- 
in cards or special switches). Soft-lce/W, M ultiscope, and Periscope are examples of 
debuggers that arenot compiler-specific. Each offers featuresunavailablein compiler- 
supplied debuggers. 

Codeview 

M icrosoft's Codeview debugger has been around for a long time. Its predecessors 
include the DOS DEBUG command (a crude and simple debugger) and the 
SYM DEB debugger. 

You can debug most complex programs with Codeview. Codeview enablesyou 
to debug to a serial monitor or to configure two monitors for debugging. U nder 
W indows, you can debugtoaseparatewindow. U nlessyou havealargescreen monitor 
and a high-resolution video system (1024 x 768 at a minimum), however, this mode 
of debugging can be difficult. 
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QuickC for Windows 

QuickC for Windows from M icrosoft offers an integrated debugger. (It doesn't have 
its own name because it is part of Q uickC 's I ntegrated D evelopment E nvironment.) 
This debugger can debug only at the C source level; it cannot debug in assembly. 
T herefore, you must have the source code for the sections of the program that you 
want to debug. 

W hen using Q uickC 'sdebugger, you losetheadvanced featuresof theW indows 
debugging kernel, which helps find programming errors caused by incorrect calls to 
Windows functions. 

Turbo Debugger 

Borland'sTurbo Debugger enables you to debug programs compiled with Borland's 
compilers. Thisdebugger offersmany of thefeatures found in M icrosoft'sCodeview, 
including dual-monitor support and the ability to use a debugging terminal. 

Watcom'sVIDEO Debugger 

When using Watcom's 32-bit compiler (Watcom C/386), you have access to their 
debugger, called VIDEO. This debugger offers many interesting features. The 
compiler iscompatiblewith DOS, W indows, and 0 S/2, sothedebuggersupportseach 
of these environments, as well asQ NX. 

VIDEO, like many of theother debuggers, offers dual-monitor support. It also 
debugs using two PCs linked by serial ports, by parallel ports, or over networks. 

Efficiency 

Program efficiency is an important aspect of programming. 1 1 doesnot matter how well 
your program performs if it takes forever and a day to accomplish the job. Efficiency 
con si sts of many parts— you can n ot u se som e aspects of creati ng an efficient program 
while ignoring others 

Statements that slow a program usually arein loops. For example, atypical fort) 
loop that calls somefunctions can use a lot of time. When you write a loop, consider 
how many times the loop will be executed, which functions are called, and what the 
functions are doing. If the loop will be executed a large number of times (thousands 
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of times or more), you should consider optimizing the loop. When efficiency is the 
most important objective, you can sometimesmaketheprogram run faster by coding 
a frequently called function inline, instead of calling the code as a function. 



32-Bit Programs 

Most PC programming uses the 16-bit programming model. Every timea i ong int 
is added, two 16-bit adds are performed. For programs that will be running only 
on 386 (or higher) C PU s, it might be more efficient to usethe32-bit instructionsthat 
these CPUs offer. Remember, however, that a program written for the 32-bit 
instruction set of the 386 cannot run on a 286 or an original PC . 

Programswritten usingthe32-bit modeof theC PU run only in protected mode. 
Therefore, an interface is required between DOS (which runsonlyin real mode) and 
your application running in 32-bit mode. This interface is called DPM I (DOS 
Protected M ode I nterface). Following is a list of common D PM I products: 

• M icrosoft W indows 3.1 in 386 enhanced mode provides DOS sessions with 
DPM I service by Windows. This interface is included with Windows 3.1 at no 
charge. 

• DOS/4G from Rational Systems, Inc. (and DO S/4GW, which is supplied 
with Watcom'sC/386 compiler) provides the necessary DPM I services for 
your programs. DOS loads DOS/4G each timea program that must use its 
services is loaded by the user or executed by DOS. 

• Phar Lap 386/D OS-Extender from Phar Lap Software, Inc. is another DPM I 
interface. It is similar to DOS/4G in that it is loaded each timeaprogram 
requiring its services is executed. 

• OS/386 from ERGO Computing, Inc. provides D PM I services. Because 
OS/386 isaTSR, it must be loaded only once. The drawback is that the 
DPM I interface continues to occupy memory after the program that required 
it completes its execution. 

• Intel Code Builder is another DPM I system. 

• 0 S/2 V 2 from I B M . T his is not a true DPMI because it is not M S-D OS. It is, 
however, a competent 32-bit platform, offering one of the best 32-bit environ- 
ments with someM S-D OS compatibility. Watcom'sC-386 is an excellent 
32-bit compiler for OS/2. 
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• W indows N T from M icrosoft is a 32-bit operating system that is not C PU - 
dependent. The user interface of this OS, which was initially produced for 
386/486 CPU sand the M IPS ARC CPU, resembles Windows 3.1. To write 
W indows N T software, you must have a special version of M icrosoft C 7 that 
produces 32-bit code. 

A number of 32-bit C compilers support C++ as well as standard C program- 
ming. Themore popular 32-bit C compilers include thefollowing: 

• Watcom C/386 is an excellent compiler that you can use to develop applica- 
tions that execute under M S-DOS, OS/2 V2, and W indows 3.x. This com- 
piler supports only C programming, but the C++ version should be available 
soon. A royalty-free copy of D 0 S/4G W isincluded with Watcom C/386, and 
thecompiler supports all other D PM I interfaces (seethe preceding list). 

W atcom's compiler provides the only 32-bit support for W indows 3.1. T he 
ability to write 32-bit Windows programs is a powerful feature that should not 
be ignored by W indows programmers. 

• M icroway N DP C/C++ is an expensive compiler that offers much to program- 
mers writing math-intensive code. This compiler has excellent support for 
math coprocessors but lacks a D PM I interface program, so one must be 
purchased separately. 

• Zortech C/C++ is a compiler that can produce either 16-bit or 32-bit pro- 
grams. It comes with a D PM I program (called DOSX) that you can use 
royalty-free, or you can use Phar Lap's DOS Extender. 

• Intel's Code Builder provides a 32-bit compiler based on M icrosoft'sC 
compilers. This product is most compatible with theM icrosoft compiler. 
Version 1.1 supports 386M AX and Q EM M -386 as well. 

Creating 32-bit code can improve your program's performance from several 
standpoints. 0 ne, you can perform math on 32-bit data objects. Two, your program 
can access protected-mode memory. M any D PM I programs provide access to virtual 
memory, allowing truly large programs. Finally, 32-bit programs are more compact 
(after they are loaded into memory). I n summary, if you can livewith applicationsthat 
run only on 386 (and greater) systems, converting to a 32-bit compiler can substan- 
tial I y i m prove the perform an ce of you r program s. 
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Compiler Optimization 

0 ne of the easiest waysto gain moreperformancefrom your applicationsisto havethe 
compiler optimize the program. M ost compilers allow optimization for size(impor- 
tantif you aredeveloping for a plain DOS environment with its640K memory limit) 
or speed. Somecompilers optimize both for size and for speed, although you cannot 
ensure that compromises between the two will produce code that is both small and 
efficient. 

Typical optimizations are shown in Tablel6.2. If an optimization isnot offered 
by your compiler, another optimization might perform a similar task. 



Table 16.2. Typical optimizations for compilers. 



Microsoft 


Borland 


Watcom 


Function 


/GO 


- 1- 




Generate code for 8086 


/Gl 


■ i 




Generate code for 80186 


/G2 


■ 2 




Generate code for 80286 


/G3 


- 3 




Generate code for 80386 


/G4 


HI A 




Generate code for 80486 


/Gc 


- P 




FORT RAN /Pascal calling 
conventions 


/Gr 


■pr 




Register calling 
conventions 


/Gs 


- N- 




Remove stack overflow 
checks 


/Gy 






Function-level linking 
(links only called 
functions) 


10, /Ot 


-Ox, -G, 
- Ot 


/ot 


M inimize execution 
speed (default) 


/Oa 


-Oa, -G- 


/ oa 


Assume no aliasing 
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/ Ob n -Oi 

/Oc -Oc 

106 -06 

I Oe - Oe 



/Of 
/Of- 



/Og -Og 

/Oi -Oi 

/OI -OI 

/On - OI - Om 



/ Oo 



/ Oo- 
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Function 

Control inline 
expansion (n 
is a digit from 0 
through 2) 



Enable block-level 
common subexpression 
optimization (default) 

io6 Turn off all 

optimization 

Ignore register keyword 
and allow compiler to 
perform global register 
allocation 

Turn on P-code quoting 
(default) 

Turn off P-code quoting 

Enable global-level 
common subexpression 
optimization 

/oi Generate intrinsic 

functions 

/oi Enable loop 

optimization 

Turn off potentially 
unsafe loop 
optimizations 

Turn on post code- 
generation optimizing 
(default) 

Turn off post code 
generation optimizing 

continues 
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Table 16.2. continued 



Microsoft Borland Watcom Function 

/op Improve float 

consistency 

i on hi a Turn on P-code 

optimization 

/or hi a Enablesingleexit 

point from functions 
(useful when debugging 
with CodeView) 

/os -01, -os /os M inimize executable 

file size 

/ o v hi a Sort I ocal vari abl es by 

frequency of use; P- 
code only (default) 

/ov- hi a Sort local variables in 

the order that they 
occur; P-code only 

i on Assume aliasing across 

function calls 

/ox -ox / o x a t M axi mi ze optimization 

/oz Turn on potentially 

unsafe loop 
optimizations 



Asyou can see from Table 16. 2, each compiler offers somesimilar optimization 
options. The M icrosoft compiler offers more different optimizations, but some of 
these are specific to how thecompiler works (such as the M icrosoft compiler'sability 
to generate P-code). 

Someof themorecommon optimizations include loop optimization, intrinsic 
function generation, and common subexpression optimization. T hesearethesubjects 
of the foil owing sections. 
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Loop Optimization 

I n loop optimization, express onsthat always resultin thesamevaluearemoved outside 
the loop. An example of this follows: 

/ / Local (auto) variables: 
i nt i =0; 
i n t x = 1; 
i nt y = 2; 

whi I e( i < 2 5 0) 

{ 

i += x + y ; 
OurFunction(i); 

} 

Thevalueof the i variable is incremented by thesum of x and y. The values of 
x andy do not changeintheloop, so their sum doesnot change. However, x andy are 
summed each timetheloop isiterated. Perhapstheprogrammer could bemorecareful, 
but I have found it difficult to catch simplethingssuch asinvariant expressions. 

When the compiler performs a loop optimization, it modifies the code to 
resemble the following: 

/ / Local (auto) variables: 
i nt i =0; 
i nt x = 1; 
i nt y =2; 

// Compiler added temporary storage: 
int temp = x + y; 

whi I e( i < 2 5 0) 
{ 

i += _ _t e mp ; 
Ou r F u nc t i o n ( i ) ; 

} 

Notice that the compiler has created a new temporary variable (which actually 
doesn't have a name). This temporary variable is assigned thesum of x and y. In the 
loop, i isincremented by thevalueof thetemporary variable, so thesum doesnot have 
to be recomputed for each loop iteration. 
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Sometimes loop optimization can create problems during debugging. For 
example, suppose thereisa problem in thetemporaryvariable'scomputation (such as 
a divide- by- zero error). The line number for the error will not match a line in the 
program, making it difficult to determine the location of the error. As well, when 
tracing the program's execution, the machine instructions will not have a linear 
correspondence to the source code lines, making it more difficult to debug the 
program. For these reasons, you might want to turn off loop optimization when you 
initially debug your program. 

Generating Intrinsic Functions 

The library functions are defined as separate, callable functions. Some compilers, 
however, can gen erate inline cod e f or many library functions. Inlinecode generation 
forthesefunctionssavestheoverhead of afunction call, which can beimportant when 
the function is called from a loop that has many iterations. 

Thefunctionsin Table 16.3 have intrinsic forms. Only the AN SI functions are 
listed. Each compiler, however, offers a number of other intrinsic functions that are 
compiler-specific. 



Table 16.3. AN SI -supported intrinsic functions. 



Function 


Microsoft 


Borland 


WatcomC/386 


abs() 


V 




V 


acos ( ) 


V 






as i n ( ) 


V 






at a n ( ) 


V 






at a n 2 ( ) 


V 






cei 1 ( ) 


V 






cost ) 


V 






cosh( ) 


V 






di v{) 






V 


exp() 


V 






f abs() 


V 


V 


V 
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Function 


M icrosoft 


Borland 


Watcom C/386 


f 1 oo r { ) 


V 






f mod ( ) 


V 






i np( ) 






V 


i n pw( ) 






V 


1 abs() 






V 


1 abs() 


V 






1 di v() 






V 


1 og( ) 


V 






1 o g 1 0 ( ) 


1 

V 






me mc h r ( ) 




V 


V 


me mc mp ( ) 




V 


/ 


me mc p y ( ) 


/ 


/ 




me ms e t ( ) 


V 


V 


V 


mo v e d a t a ( ) 






V 


out p( ) 






V 


out pw( ) 






V 


pow( ) 


V 






rotl ( ) 




V 




rotr{) 




V 




si n( ) 


V 






si nh ( ) 


V 






sqrt ( ) 


V 






st pcpy( ) 


V 


V 




st rcat ( ) 


V 


V 


V 


st rchr ( ) 




V 


V 



continues 
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Table 16.3. continued 






R f\f\ anrl 


VV dllUIII V./JUU 


st r c mp( ) 


y 


y 




strcpyl ) 


i 

y 


i 

y 


V 


st r 1 en{ ) 


y 


y 


V 


st r neat ( ) 




y 




s t r n c mp ( ) 




V 




st r ncpy( ) 




V 




s t r n s et ( ) 




V 




st r r c hr ( ) 




V 




tan() 


V 






t a n h { ) 


V 







Theonly disadvantage to using intrinsic functions is that they increasethesize 
of the compiled code. For example, if stri end is called 50 times in a program, an 
intrinsicfunction will generate50copiesofthecodethatdoesthestringcopy, whereas 
the library function would generate one copy. 

Common Subexpression Optimization 

W hen performing common subexpression optimization, thecompiler rep laces redun- 
dant expressions with a single common subexpression. This process is similar to loop 
optimization. An example of a common subexpression follows: 

k = 20; 

i = k + 10; 

j = k + 10; 

T he compiler optimizes this code as 

k = 20; 

int _ t e mp = k + 10; 
i = _ _ t e mp ; 
j = _ _ t e mp ; 
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Asin loop optimization, thecompilercreatesatemporaryvariablethatholdsan 
interim value. Often, thecompiler can storetheresultofthecomputation in a register, 
so no memory is used. H owever, the statement's location in the code (including the 
presence of intervening statements), dictates how the compiler processes the source 
code. 

Common subexpression optimization is subject to the same problems as loop 
optimization (see the "Loop Optimization" section). 



Direct Video I/O 

At onetime, almost all programsdid direct video I/O because the original PC video 
systems(such astheCG A) werenot designed for speed. To update thevideo quickly, 
programs had to write directly to the video's memory. 

You should consider several factorswhen deciding whether your program should 
support direct video. First, thedisplay adapters in usetoday(someareEGA, but most 
are VGA) are better performers than the old CGA standard of 10 years ago. 

Second, to support direct video I/O , your program must support a number of 
standards. Each system (CGA, M DA, EGA, and VGA) manages its display memory 
differently, with different buffer locations and arrangements in memory. 

Do you access video memory directly? For most applications, there are better 
ways. For example, if you write a Windows or OS/2 application, accessing video 
memorydirectlyisunacceptablebecauseWindowsmanagesthevideo. In addition, the 
efficiency of VGA video systems makes direct I/O unnecessary. 

Some programmers assume that you must use direct video I/O to perform 
random writesto thescreen (perhapsto placea messagebox i n thecenter of thescreen) . 
This is untrue. On the PC, you can use the AN SI .SYS device driver for many screen 
operations, such as color changes and direct cursor addressing. 



Floating-Point Optimization 

You can significantly improve a program that relies on floating-point math (that is, a 
program that has data types of f i oat , doubi e, or i ong do u bi e ) by using the proper 
floating-point compile and link options. 
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M icrosoftC hasfiveoptions(and varioussuboptions) forfloating-point support. 
You can choose from three libraries when linking floating-point programs. These 
libraries control calls to floating-point routines: 

• The Alternately ath Package Library (mLIBC A. LIB) generates calls to 
floating-point math routines. There are both thetruefloating-point functions 
and routines to emulate the math coprocessor. If a coprocessor is installed, this 
package simply ignores it. This library produces the smallest executable 
program, but it does not support i ong double datatypes. 

• TheEmulator Library (mLIBCE. LIB) generates calls to a library of functions 
that emulate the 80x87 math coprocessors. Floating-point functions are 
contained in thelibrary; these functions also call theemulation routines rather 
than usea floating-point coprocessor. 

• The Coprocessor Library (mL I BC 7.L I B ) isnota library for support of 
floating-point operations because all floating-point operations are coded inline 
and are performed using an installed math coprocessor, which is required. 
Floating-point functions are contained in thelibrary, and these functions also 
usethefloating-point coprocessor directly. A math coprocessor is required to 
execute a program linked with this library. 

These libraries are used with the floating-point compiler options, which areas 
follows: 

/FPa Your code generates calls to a library. You can select which 

library is linked: mLIBC A (the default), mLIBCE, or mLIBC 7. 
(mLI BC 7 does not take advantage of inline instructions to the 
math coprocessor). 

/fpc Your code is similar to that generated with / f Pa , except the 
default library supports i ong doubi e. You can select which 
library is linked: mLIBC A, mLIBCE (the default), or mLIBC 7. 
(mLI BC 7 does not take advantage of inline instructions to the 
math coprocessor). 

/ f p c 8 7 Your code requires a math coprocessor. This option isagood 
choice if you know that the target computer has a math 
coprocessor. T he code is similar to that generated using / f pc . 
You can select which library is linked: mLIBCA, mLIBCE, or 
mLIBC 7 (the default). 
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/FPi Your code is generated using interrupts for floating-point 

operations rather than inline floating-point instructions The 
software interrupt handler then checks whether a coprocessor is 
installed. If a coprocessor is installed, the handler patches the 
code to support the coprocessor. A problem with some compil- 
ers is that this technique creates self-modifying code, some- 
thing that does not work well under protected mode, in which 
code segments can be read only. You can select which library is 
linked: mUBCA, mUBCE (the default), ormLIBC7. 

/ FPi 8 7 Your code is generated using interrupts for floating-point 

operations. T he software interrupt handler then checks to see if 
acoprocessor isinstalled. If one is installed, the handler patches 
the code to support the coprocessor. One problem with some 
compiler versions is that this technique creates self-modifying 
code, something that doesn't work well under protected mode 
where code segments may be read only. You can select which 
library is linked: mUBCA, mUBCE, ormLIBC7 (the default). 

T he default option is / f p i , which works for most applications. 



Inline Assembly 

T here is no argument about it— well-written assembly creates the fastest and smallest 
programs. H owever, many programmers are uncomfortable writing even small 
programsin assembly, let alonea major project. Writing an assembly program can take 
five times as long as writing a C program, and there may be five times as many lines 
in an assembly program, and five times as many chances to makea mistake. 

One quick and not too difficult solution is to use inline assembly. In this 
technique, you useC to develop theunderlying foundation forafunction, then write 
the critical code in assembly. One useful feature of this technique is that you could 
writetheentirefunction in C, then after determining that theprogramisfunctioning 
correctly, rewrite the function's critical parts using inline assembly. 

I nlineassembly comes with a price, however. One problem isthat thecompiler 
cannot perform many of theoptimizationsitcan do for a normal C function. This is 
not too critical if most of thefunction is written using inlineassembly. Ifthefunction 
is written primarily in C with only a small part using inlineassembly, the lack of full 
optimization may be a problem. 
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Another problem is that any function that relies on inline assembly is not very 
portable. If you plan to run your application on different computer systems, you may 
want to avoid inline assembly. 



Linking for Performance 

Some linker options affect the application's performance. These options can create 
problems if you do not understand what they do. 

0 ne important factor in creating an efficient executable program is to be sure 
that the linker is not including any debugging information (such as line-number 
tables) in the executable program. Weoften remember to compilethefinal versions 
of our programs with the correct compiler options, then forget to change the link 
options. 

M any link programs have options that pack the executable program. These 
options are categorized as follows: 

• Packing redundant bytes. Using a simple compression technique, the link 
program can pack multiple occurrences of bytes with thesamevalue. M ost 
linkers pack only bytes that are zero (because multiple bytes of a nonzero value 
are rare). W hen the program is loaded, the loader expands these bytes to their 
original count. This process reduces the size of the executable file and may 
shorten the load time. 

• Packing code segments. When a program is created on the PC using the Large 
or Medi um compiler option, each sourcefilehas its own codesegment. Often, 
several of these segments can be combined, and then calls to functions in the 
combined segment can be converted to near calls (which are faster than far 
calls). 

• Packing data segments. When a program is created on the PC using the Large 
or compact compiler option, each sourcefilehas its own data segment (assum- 
ing that the segment has sufficient data). Often, several of these segments can 
be combined into one. 

One way to make an application more efficient is to write it as an overlay 
program. Themain advantageisthatRAM doesnot have to be permanently allocated 
for infrequently called functions. This leaves more memory for data storage (perhaps 
eliminating the creation of temporary work files). A disadvantage of overlays is that 
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many linkers requireyou todeterminewhich functions are part of which overlays. In 
addition, overhead is incurred when functions not currently in memory must be 
loaded. 



Pascal and cdecl Calling Conventions 

Calling conventions are the rules on how parameters are passed to a function being 
called, and whether thecaller or thefunction being called is responsiblefor removing 
the parameters from the stack when thefunction is finished. 

For many functions, using the Pascal calling method is slightly more efficient 
than the native C calling conventions. The degree of performance improvement 
dependson thenumber of parameters and how often thefunction iscalled. N otethat 
the Pascal calling conventions cannot be used with a function that has a variable 
number of arguments 



Precompiled Headers 

Using a precompiled header increases the performance of the compiler when it is 
compiling the program but does not affect the performance of the application while 
it isexecuting. I f you are spending too much timecompiling your programs, look into 
the benefits of precompiled headers. Borland compilers and M icrosoft compilers 
support precompiled headers. 



Using 80286/80386/80486 Instruction Sets 

The use of the 80286 (or 80386 or 80486) instruction set is an overlooked but 
important way to improve program performance. An 80486 executes all instructions 
that an 80286 executes, but the reverse is not true. After a program iscompiled using 
a specific CPU's instruction set, it will not run on a CPU that is less than thetarget 
CPU. 

Windows supports only the 80286 instruction set and above, so you should 
always compile W indows applications using the 80286 options. 



671 



Part IV • Documenting the Differences 



M ost of the power of the 80386/80486 cannot be utilized unless your applica- 
tion supports the CPU 's 32-bit mode. Because this requires a 32-bit compiler, you 
must plan ahead for 32-bit programs, ensuring that you have access to the necessary 
compiler. 



Using a Source Profiler 

One way to make an application more efficient is to determine which functions take 
the most time, then optimize them. Guesswork will not work— you cannot look at a 
function and determinethat it is using a lot of C PL) resources. You must use a source 
code profiler to determine where the most CPU time is being spent in your program. 

M ost sou rce code prof i I ers work by setting a very fast clock i nterru pt. E ach ti me 
an interrupt occurs, the profiler records the name and address of thefunction that is 
executing. A second program then correlates the function and address information, 
and creates a sou rce file/function tablethat shows where most of the time was used. 



Using Intrinsic Functions 

When your application calls a library function (such asstrieno), overhead is 
incurred: thefunction'sargumentsareplaced on thestack, registers are saved, and the 
function is called. When thefunction returns, the arguments must be removed from 
the stack and the registers must be restored. 

M anymodern C compilers enableyou to su bstitute i n I i ne code for common C 
library functions. T his diminates much of theoverhead for a function call, but at the 
expense of having more than one copy (usually many more copies) of the code that 
performs the function. 

When you use an intrinsic function in a loop and thefunction is called many 
times, you can boost theloop'sperformancesubstantially. (SeeT able 16.3 for a list of 
wh i ch f u n cti on s are avai I abl e as i n tri n si c f u n cti on s. ) 
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Using Memory Models 

W hen programming for a computer that uses segmented memory architecture, such 
as the PC, you can choose which memory model the compiler uses. For small 
programs, any memory model usually works. The issue is to use the most efficient 
memory model for the task at hand. Each memory model has both benefits and 
drawbacks, as shown in Table 16.4. 



Table 16.4. Memory models. 



Model 



Description 



Attributes 



Ti ny 



S ma I I 



Me d i um 



Compact 



One segment for both 
data and code 



One segment for data, 
and one for code 



One segment for data, 
and separate code segments 
for each source module 



Separate data segments for 
each module, and one segment 
for code 



Fast and small, usable 
only with .COM files. 
The total size of the data 
and the code cannot 
exceed 64 K. 

Fast and small, usable 
only with .EXE files. 
Neither the code nor the 
data can exceed 64K each. 

Calls are slower, but 
data can be accessed 
quickly because it is 
always in the default 
data segment. T he code 
may be as large as 
necessary (to the limits 
imposed by the system 
RAM ), but the data 
cannot exceed 64 K. 

Calls are faster, but 
data accesses are 
generally performed using 
FAR pointers, which slow 
data accessT he program's 



continues 
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Table 16.4. continued 



Model Description Attributes 







code cannot exceed 
64K. The data is limited 
only by the amount of 
available RAM . 
Individual data objects 
cannot exceed 64K in 
size. 


Large 


Separate data segments for 
each module and seoarate 

ViVlV' II III V/ VI Vl 1 \m*f 1*1 1 1 Vl JVM VII Vl VV* 

code segments for each 
source module 


Calls are slow and data 
accesses are aenerallv 

vi v, v. vjj^j vii V- vj i v*i vii i y 

performed using far 
pointers, which slow 
data access. The 
program's code and data 
are limited only by the 
amount of available RAM . 
Individual data objects 
cannot exceed 64K in 
size. 


Huge 


Separate data segments for 
each module, and separate 
code segments for each 
source module 


Calls are slow and data 
accesses are generally 
performed using FAR 
pointers, which slow 
data access. The 
program's code and data 
are limited only by the 
amount of available RAM . 
Individual data objects 
can be larger than 64K. 



M ost programs can be written using the s ma 1 1 model. Programs with a large 
amount of code or data often needtheLarge (or Huge) model. 
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Summary 

In this chapter, you learned how to debug a program and improve a program's 
performance. 

• T here are a number of common bugs. C necking your code for these common 
bugs first can save debugging time. 

• TheC asserto macro assists in debugging. It enablesyou to test a condition. 
If the condition fails, the program ends with a diagnostic message. 

• If a debugger is unavailable, writing a debug output function can save time in 
determining theflow of a program. 

• M ost compilers come with a debugger. 

• M ost debuggers require a substantial setup and learning curve. 

• A debugger is the only effective way to find some problems. 

• When programming for efficiency, you can program in the 80386/80486 
32-bit mode if your compiler supports such a mode. 

• Using the compiler's optimization can make your program run faster. Gener- 
ally, you should develop the application with optimization turned off. When 
the application is finished, turn on optimization and retest the application. 
Sometimes, the compiler's optimization will cause a program to fail that 
worked with optimization turned off. 

• Inline assembly can be useful for creating fast functions without resorting to 
full assembly code. 

• A source profiler can determine which parts of your program are executed 
most frequently. By combining these routines, you get the maximum benefit 
from hand optimization. 

• I ntrinsic functions allow thefunction's code to be placed inline rather than 
being called. Although intrinsic functions increase the program's size, they can 
greatl y en h an ce th e program 's efficien cy. 

• T he memory model you choose for a program affects its performance. C hoose 
thesma 1 1 model for small, simple programs. 
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Table A. 1. The ASCII Character Set 
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T his appendix reviews four popular C compilersforthePC. Each compiler enables 
you to compileAN SI C programs, and each offers enhancements as well. Though all 
share a number of common enhancements, no one compiler offers everything. 

These products are covered in alphabetical order by their supplier. Thisis not a 
critical review of these compilers; my intent is to simply discuss the features and 
possible shortcomings of each product. 

I use all four of these products; however, it is impossible for me to be fully 
conversant on all features and parts of these products. All are versatile products, 
providing many features and utility programs. If I'venot covered something regard- 
ing any of the compilers, I apologize. 

Borland also offers entry-level Windows- based development systems in Turbo 
C++forWindowsandTurboC++forDOS. I do not havethese products, sol cannot 
comment on them, but both products have received good reviews in magazines and 
should serve you well. 
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Borland'sC++3.1 

It's big! Thiscompiler requiresabout50M hard disk space an da reinforced bookshelf 
to hold thedocumentation. Borland, in creating itspremiereC ++compiler, madeone 
of its nicest products yet. 

This product fully supports both DOS and Windows development environ- 
ments. Generally, you can develop applications for the same environment in which 
the IDE (integrated development environment) is running; I'd recommend using 
the W indows version— it's a slick, easy to use I D E . 

With its EasyW in program, Borland C-H-can migrate a character-based DOS 
application to Windows by creating a single window that serves for the screen. This 
window displays both STDOUT and STDERR, while the STD IN input comes 
from the keyboard. The appearance of these applications is good; however, the 
application does not have a menu bar. Borland C++ determines the type of applica- 
tion by analyzing the ma i n( ) function— if it hasamai no function, the application is 
a DOS application and will be built as an EasyW in program; if it hasawi nMai n( ) 
function, it is a W indows program. 

You can reducediskstoragerequirementsbyinstallingonlythesystem partsyou 
plan to useand leaving out somecomponents, such as sample code, library source, and 
Windows specific components. N ot everyone wants to develop Windows programs. 
H owever, W indows is becoming a popular environment for programmers who want 
to create applications with slick user interfaces. 

Someof the most significant features of theBorland C++3.1 compiler include: 

• Powerful and slick W indows I D E for programmers who develop W indows 
software. 

• Competent DOS-based IDE, offering manyfeaturestheWindowslDE offers 
(although you can't cut and paste from other applications, as you can with 
Windows). 

• For Windows developers, Borland offers the Workshop. This program enables 
you to modify the resources of existing applications, such as dialog boxes, 
menus, icons, cursors, and bitmaps. The Workshop is powerful: you don't 
need the source code for the program you are modifying. You can change 
applications you didn't write— modifying that menu you don't like or that 
awkward dialog box because it works on an .EXE file. You can, of course, 
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develop your own application's resources using W orkshop. This one program 
replaces M icrosoft's DIALOG and I MAG ED IT programs, while adding many 
new features. 

• For Windows developers, Borland offers a powerful window-monitoring 
facility. It lists, in a listbox, all existing windows and their relationships. This 
feature is much more flexible than M icrosoft's SPY (which requires you to 
hunt for a given window). After you select a window, you can monitor the 
messages passed to and from it. 

• For Windows developers, Borland offers an import library generation tool. 
This program works much like M icrosoft's I M PLIB program, but runs under 
Windows. You use an import library tool to develop .DLL (dynamic link 
library) files 

• For Windows developers, Borland offersTurbo Debugger for Windows. This 
debugger has many powerful features such as remote debugging, dual monitor 
use, and network-based debugging. 

• For Windows developers, Borland offers a source code profiler. This profiler is 
useful for determining which parts of an application consumethe most CPU 
resources. It istuned for Windows applications. 

• For Windows developers, Borland offers a UAE monitor (much like 

M icrosoft's D r. W atson). T his program, which runs constantly, traps hardware 
exceptions generated by some types of programming errors and creates a log 
fileof information you can use to help debug the application. 

• For Windows developers, Borland offers a file conversion utility to convert 
OEM characters to ANSI. This program helps make files created under DOS 
that have special characters Windows compatible, without a long conversion 
edit session. 

• For Windows developers, Borland offers a hot spot editor. This utility is from 
M icrosoft and is the standard W indows SD K hot spot editor. 

• Borland's C++ 3.1 offers precompiled headers. A flexible implementation, 
precompiled headers help speed up the creation (compilation) of large, multi- 
source file projects. 

• Besides the various programs, an extensive online help system is provided. 
Online help is becoming increasingly important because the documentation 
for many compilers (including Borland's) often exceeds 10,000 pages. 
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When managing large projects, a make facility is necessary. Borland's compiler 
offers both the I D E's make facility and a stand-alone make that you can run under 
DOS. 

When used under Windows, Borland C++ creates a program group liketheone 
shown in FigureB.l. Thisgroup givesyou accesstoeach ofthefeaturesBorland'sC++ 
offers to theWindows programmer. 
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FigureB.l. Borland's C++ Group under Windows. 



W hen you start the I D E under W indows, you get an attractive application that 
enables you to do thefollowing: 

• Define what files make up the application. 

• Define the application's attributes (for example, whether it is a Windows 
application or a D LL). 

• Edit the application's files. 

• Compileand linktheapplication. 

• Debug and run the application. 
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Various configuration options control the environment, compiler and linker 
options, and project options. Borland's C++ IDE (under Windows) is shown in 
Figure B.2. Borland's C++IDE under DOS isshown in Figure B.3. 



B- 



File Edit Search Run Compile Project Browse Options Window 



Help 



ttinclude <stdio.h> 
ttinclude <stdlib.h> 

int main ( ) 

C 

char szBufferC256]; 

printf ("XnHello there from borland\n\n") ; 

gets (szBuf f er ) ; 

printf C'xsVlVi", szBuffer) ; 
printf ( "*s\nW , szBuffer) ; 
printf ("xsViNn", szBuffer) ; 

printfCT'm done! ! T TNn") ; 
return (0) ; 



Figure B. 2. Borland's C++IDE under Windows. 



Notice the similarity between the IDE under DOS and the IDE under 
Windows. The main difference isthe lack of the push-button toolbar under DOS. In 
theWindowslDE, it is found just under the menu structure. Under theDOS IDE, 
the lack of this toolbar isn't a major problem for most programmers because the 
functions in thetoolbar are available as menu functions. 

A shortcoming of the Borland products is they produce only 16-bit code. 
H opefully, Borland will soon make a 32-bit code-generating compiler. 

Generally, Borland'sC++compilersarewell designed and area pleasure to use, 
especially under W indows. 
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Microsoft 

M icrosoft currently markets two C compilers. Their main product, C/C++ V 7.0, 
is massive. It has documentation for C, C++, and Windows, and requires a large 
amount of disk space. 

M icrosoft's entry-level compiler, QuickC for Windows, is similar to M icro- 
soft C 6.00. QuickC for Windows currently supports only Windows 3.0. 



C/C++ 7.0 

M icrosoft's mainline C compiler supports C ++ and has a number of new features 
including incorporation of the Windows SD K with Version 7.0. This compiler is 
certainly technically competent, but some of its features lag behind the competition. 

For one thing, although M icrosoft's compiler probably produces the best 
com pi I ed code— h avi n g exten si ve opti m i zati on s an d a I on g track record as a tru stwor- 
thy com pi I er— i t of f ers on ly a D O S- based I D E . T h e creators of W i n do ws sti 1 1 h aven 't 
created a true, top-of-the-lineWindowsdevdopment system, which could be viewed 
as a serious omission. 
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Some of the notable features of M icrosoft's C/C++ 7.0 include thefollowing: 

• Competent DOS-based IDE with many of the same features that are offered 
by Q uickC for W indows IDE. You must still use a D 0 S window to create and 
compileyour Windows applications. 

• For W indows developers, M icrosoft offers a series of programs to develop a 
Windows program's resources. These programs enable you to modify the 
resources (objects such as dialog boxes, menus, icons, cursors, and bitmaps) of 
applications you're developing. These programs include M icrosoft's D I ALOG 
and IM AGEDIT. 

• For Windows developers, M icrosoft offers a window-monitoring facility called 
SPY. After selecting a window, you can monitor the messages passed to and 
from it, sending the output from SPY to either a window, a file, or the debug- 
ging terminal if one is attached to C 0 M 1. 

• For Windows developers, M icrosoft offers an import library generation tool. 
You use an import library tool to develop .DLL files. 

• For Windows developers, M icrosoft offers CodeView 4.0, acompetent 
debugger for W indows. T his debugger has many powerful debugging services, 
such as remote debugging and dual monitor use. 

• For Windows developers, M icrosoft offers a source code profiler, a useful 
tool in determining which parts of an application consumethe most CPU 
resources. This profiler is tuned for Windows applications. 

• For Windows developers, M icrosoft uses Dr. Watson (which is part of Win- 
dows 3.1) as a U AE monitor. This program runs constantly in the back- 
ground. It traps hardware exceptions generated by some types of programming 
errors and createsalog filethatyou can use to help debug the application. 

• For Windows developers, M icrosoft offers a hot spot editor, the standard 
W indows SD K hot spot editor. 

• M icrosoft's C/C++ 7.0 offers precompiled headers. Less flexible than Borland's 
implementation, they are still helpful to speed up the creation of large, multi- 
source file projects. 

• Besides the various programs, an extensive online help system is provided. 
Online help is important because the documentation for many compilers 
(including M icrosoft's) often exceeds 10,000 pages. 
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0 nedownsideisthiscompiler requiresatleast an 80386CPU orfaster. Itcannot 
run on an 80286 or slower C PU . For professional developers, thismay not bean issue, 
but for those of you who program as a hobby, it's important to check whether the 
compiler runs under your hardware. 

When m an agi n g I arge p r oj ects, a m ake f aci I i ty i s n ecessary . M icrosoft's compiler 
offers both the I D E 's m ake f aci I i ty an d a stan d-al on e m ake ( N M A K E ) , both of wh i ch 
you can run under theD 0 S prompt. N M AK E accepts standard .M AK files(which can 
be written by hand); however, the ID E requires a make file it has created (because of 
its rather strict contents rules). You can take the I D E's make file and use it with 
N M AKE without modifications. 

When used under Windows, M icrosoftC/C++creates a program group likethe 
one shown in Figure B. 4. This group gives you access to each of the features that 
M icrosoft's C/C++ product offers to theWindows programmer. 



Online help 

Windows ■ 
debugger 

DOS- 

debugger 




Di WalsonMiaosoltWoid 



Fnlmn^dMnrfeD,!,,,,, Window, 3.1 



Figure B.4. M icrosoft's C/C++ Group under Windows. 



W hen the I D E starts under W indows, you arepresented with a character-based 
DOS application. This application enables you to do thefollowing: 
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• Define the files that makeup the application. 

• Define the application's attributes (such as whether it is a W indows or D 0 S 
application). 

• Edit the application's files. 

• Compile and link the application. 

• Debug and run the application. 

Various configuration options control the environment, compiler and linker 
options, and project options. M i crosoft's C /C ++ 1 D E (under Windows) is shown in 
Figure B.5. Other powerful features include the extensive customizing ability of 
the IDE, including the ability to create functions and complex macros, which 
Borland's I D E doesn't enable you to do. 




Figure B. 5. M icrosoft's C/C ++ 1 D E (in a Windows DOS Box). 

Notice the similarity between the IDE under DOS and Borland's IDE 
under DOS. 
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W ith a D 0 S-based I D E, thelossof a tool bar isstill themain difference. Perhaps 
making up for this is thefact that for some computers, the D 0 S-based I D E is faster 
when the computer is running in a character video mode. Lack of a toolbar doesn't 
present a major problem for most programmers because the functions in thetoolbar 
are available as menu functions 

Like the Borland compilers, a shortcoming of theM icrosoft compilers is they 
produceonly 16-bit code. I h ope M icrosoft soon provides the32-bit codegenerating 
version of this product because many C programmers will bedevdoping 32-bit code 
in the near future. 

M icrosoft'sC/C ++compiler generally produces better and faster programsthan 
many of its competitors, mostly because of M icrosoft's extensive compiler develop- 
ment experience. This program is a good choice if you don't need a Windows-based 
IDE and you can live with the requirement for an 80386 or better operating 
environment. 



QuickC for Windows 1.0 

QuickC for Windows was introduced in 1991 by Microsoft as their first Windows- 
hosted I D E product for C . T his product had great potential; however, it has not kept 
its popularity. 

QuickC forWindowshasarather straightforward IDE, asshown in FigureB.6. 
This IDE has an integrated debugger (not Codeview) that allows C source level 
debugging. 

Again, asfor other W indows-based I D Es, Q uickC for W indowsoffersa toolbar 
to givequick accessto features such ascompile, compileand link, and accessto some 
debugger functions. 

This product has several advantages. 

• I 've noticed (but others who have benchmarked Q uickC for W indows don't 
agree with my results) that Q uickC for W indows is a fast compiler. 

• It iseasy to use, with its projects easy to create and build. 

• It offers theability to create DOS applications under Windows, something no 
other W indows-based I D E does. 

• It does optimizations (but not to the level that C/C++ 7.0 does). Because this 
compiler is similar to C 6, it probably could be effectively compared to C 6. 
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1 t offers, for an attractive price, an entry into W indows programming. 1 1 
includes many of thefeatures of the Windows SDK; most notably missing are 
the help compiler and the debugging version of Windows, though both can be 
purchased separately. 
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QuickC for Windows 



File Edit View Project Run Debug Tools Options Window Help 




int main(uoid); //declare main(), and the fact that this program do 
// use any passed parameters. 

int main() 

{ // first opening brace for each function is at the left margin, 
int i; // used as a for loop index 

int nCount = ; // always initialize your auto uariables 
char szString[] = "We want to impress you %d\n"; 

for (i = ; i < ; // spaces around operators 

< // Brace on it's own line. 

nCount += printf (szString, i + ); 
> /* for (i...) »/ 



return (nCount); 



// Brackets around all return oalu 



Figure B.6. M icrosoft's QuickC for Windows IDE. 



Thefollowing section outlines some disadvantages of QuickC for Windows: 

T hisproduct doesn't interact well with Windowserror trapping and debugging. 
QuickC for Windows can trap UAE's, but it doesn't provide any information to 
enableyou to locate the error. It's generally easier to bypass the QuickC for Wind- 
ows I D E and run theerrant program directly under W indows, let it U AE, and check 
theDrWatson log fileto determinewherethefailure occurred. 

Again, when using thedebugging version of W indows (an option with Q uickC 
for W indows), many of the usual errors W indows traps and makes known to the 
programmer sometimesgo unreported. Also, out put Debugstri ngo doesn't function 
when aprogram runs under QuickC for Windows IDE, making it difficult to write 
debugging information to thedebugging terminal. 
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A final and most serious defect of QuickC for Windows is that it supports 
only Windows 3.0, but not the later versions such as Windows 3.1. Many QuickC 
for W indows users hope M icrosoft will correct this problem, but M icrosoft has not 
indicated it will upgrade this product soon. However, you can purchase the 
Windows SDK, which is compatible with QuickC for Windows. 

In all, QuickC for Windows is a good way to get started writing Windows 
programs, but if you aredevdopingsoftwareprofessionally, you may find Q uickC for 
Windows too restricted. 



WatcomC/386 9.01 

If M icrosoft's QuickC for Windows and Borland's Turbo C++ for Windows are 
cars... and M icrosoft's C/C++ 7.0 and Borland's C++ 3.1 are pickup trucks... then 
W atcom's C/386 9.01 compiler is a dump truck— a big dump truck. 

Give this compiler a job and it does it. W atcom's C/386 might easily be 
described as "for professional use only." 

Themostimportantfeaturemissingin Watcom'spackageisthelD E. You must 
provideyourown source editor to createthesourcecodefiles. With so many capable 
source editors available, this is not a problem. You create the make files by hand. 
Watcom includes an effective make facility for larger programs. 

The most important aspect of Watcom C/386 is that it is a 32-bit compiler, 
unlike the other compilers I've discussed. This means you can create true 32-bit 
applications (which then require an 80386 or better to run) thattakefull advantage 
of the more powerful 32-bit C PU s. 

This product produces DOS applications (32-bit protected mode), Windows 
programs (again, 32-bit, with a special library of 32-bit Windows functions), and 
OS/2 V 2.0 programs. It also produces AutoCAD AD Sand AD I compatible code. 

Watcom C/386 offers options that take advantage of some of the 80486's 
better instructions. C ontrary to popular belief, the80486 isnot an 80386 with a built- 
in math coprocessor, but an improved CPU, offering better instruction timings, a 
built-in cache, and other features that the compiler can use. 
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Some of theWatcom C/386's advantages include: 

• Generates highly optimized 32-bit 80386/80486 code. This code allows an 
application to support a "flat" model program up to 4,000M (4 gigabytes). 

• Is both ANSI C and IBM SAA compatible. Its compatibility with Microsoft C 
makes it easy to port applications written with M icrosoft C . 

• Supports Windows 3.x, DOS, OS/2 V2.0, and AutoCAD ADSand ADI. 

• G ives optimizations for the 80486 processor. 

• W atcom C/386 includes a 32-bit protected mode DOS Extender. This 
product, from Rational Systems, has a royalty-free license. It also supports up 
to32M of virtual memory. 

• The debugger works within large 32-bit applications, using a number of 
different techniques. 

• The compiler comes with a high performance 32-bit linker. 

• The compiler executes under both DOS and OS/2. 

• The compiler supports inline assembly. 

• Source code profiler assists in code optimization. 

• Graphics library supports EGA, VGA, and SuperVGA modes. 

• Includes support for PenPoint. 

• Under OS/2, W atcom C/386 integrates with WorkFrame/2 to provide a solid 
development environment. 

• OS/2 applications can access up to 512M virtual memory. 

• Windows programs can be fully 32-bit. You don't need to develop part of the 
program as a 16-bit application and part as a 32-bit. 

• W atcom C/386 includes the M icrosoft W indows SD K components. 

• Creates 32-bit D LLswith W atcom C/386. These D LLs are easier to create 
because you don't need to consider the issues of segments. 

• W atcom C/386 offers probably the most extensive optimization possible. 
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• Watcom C/386 provides excellent error checking, including checks for 
questionable type matches, uninitialized variables, unreferenced variables, 
questionable operations, and potentially incorrect statements. 

Additionally, theWatcom C/386 includes thefollowing utilities: 

• A linker that supports 32-bit executable programs; this linker runs interactively 
or in a command-line mode. The linker supports debugging symbolic infor- 
mation (such as line numbers and variable names). There is also a protected 
mode linker that enables you to link large programs. 

• A make utility that is basically compatible with U N IX-type make programs, 
such as M icrosoft's N M AKE program. 

• A source profiler program that helps determine which parts of the program 
consume the most CPU time. 

• An object code librarian that creates! IB files. 

• A bind utility that creates 32-bit Windows programs. 

• A disassembler that can disassemble. OBJ files. This disassembler works with 
software created with Watcom C/386 and many other compilers and assem- 
blers. This tool can be invaluable when debugging software at the machine- 
code level. 

• An object (.OBJ) file converter that converts .OBJ files to other (standard) 
formats, such as M icrosoft format. 

• A comprehensive graphics library that is compatible with M icrosoft's graphics 
functions. 

The full Windows SD K is not included. Programmers who wish to develop 
Windows programs will wanttheSD K for itstoolsand documentation. Acquisition 
of the SD K solves the problem of a lack of W indows development documentation. 
This situation is also true for OS/2 V2.0 software. You will want to use IBM 's 
development tools with Watcom C/386 when developing OS/2 applications, some 
thing for which this compiler is well suited. 

Overall, Watcom C/386 is an advanced optimizing compiler that offers many 
tools, but has no I D E interface. T he programmer must set up the project by hand, 
invoke the source editor directly, and compile (or build) and correct bugs, as 
programmers have done for years. 

I hope Watcom soon offers an IDE for this compiler and thus effectively 
eliminates the C/386's only shortcoming. 
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What is C++? 

C ++ was created as a preprocessor for C and wasoriginally called C with classas, 
T hisnameproved to betoo long and was shortened to C ++. T herdationship between 
C and C++ is easy to understand: C++ is a superset of the C language. This associa- 
tion makes it easier for a C programmer to become proficient in C++ programming; 
however, if you are not yet proficient in C, jumping into C++ would bedifficult. 

The most commonly used basic reference for C++ is The Annotated C++ 
Reference M anual by M argaret A. Ellis and Bjarne Stroustrup (Addison-Wesley, 
1990). 

The C++ AN SI standards committee, X3J16, has not yet defined an ANSI 
standard, butAT&T is setting the dominant standard. AT&T's version 2.1 is the 
most commonly foil owed implementation of C ++. 0 nlyafew compiler producers still 
use version 2.0. AT&T'slater standard, version 3.0, isbeginning to be accepted and 
will soon be the most commonly implemented C++ standard. 
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Object-Oriented Programming (OOP) 

C++ was designed from theoutset to support object-oriented programming (OOP). 
To better understand OOP, you need to understand the concepts of abstraction, 
encapsulation, and hierarchies. 



Abstraction 

Abstraction isthecapacity to ignorethedetailsof an object. I n thiscase, theobject can 
be either a data object or a function. 

When you writein alow-level language, you spend a lot of time working out the 
details (at the machine level) of a process or the exact representation (the ordering of 
bits and bytes) of data objects. W ith a higher-level language, you gain the advantage 
of fewer details for which the programmer is responsible. For example, a function 
written in assembly language might require thousands of lines of code to perform a 
simpletask, whileafunction written in C might do thesametask using only hundreds 
of lines. An even higher-level language might do thetask with less than onehundred 
lines of code. 

Data abstraction might enable a programmer to look at a floating-point data 
object that contains the value 3.1415926 without considering the likely hexa- 
decimal or binary representations. 



Encapsulation 

Encapsulation istheprocessof making aclass'sinternal data partsinvisibletotheactual 
program. T he only way to access or modify a class's data is to use one of the class's 
functions. 

Limiting access to data offers two important benefits. 

• First, you don't need to consider the internal representation of the data when 
accessing it. If the data is part of an array, you don't need to question whether 
the access exceeds the bounds because the encapsulation functions can check 
for you. 
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• Second, the program is much sturdier because only a limited number of 
functions actually modify the data, and all are located within a single, defined 
part of the program. If the data is modified incorrectly, the encapsulation layer 
must be improved with better error checking and correction. 

If possible, encapsulate a class's data. Doing so makes the application more 
rdiable, and easier to modify and improve as the application grows. 



Hierarchies 

Our lives are categorized by hierarchies: our houses are organized in blocks; those 
blocks are in neighborhoods; those ndghborhoods are in towns; those towns are in 
counties; those counties are in states; and soon. 

I n programming, organizing objectsinto a hierarchy simplifies management of 
theobjects. For example, your databasemight have fidds for a dozen variables. It is 
easier to write these variables to a disk file as a single object rather than as a dozen 
separate writes, one for each fidd. 

Learning C ++ 

T he best way to learn C ++ is to first learn C , and then write a C ++ program with 
mostoftheprograminC and onlyafew lines in C++. Listing C. 1, H ELLOCPP.CPP, 
is written this way. Also notice the new filename extension, .CPP— shorthand for 
C++. .C++- isn't a valid filename extension on many computer systems. 

Listing C.l. HELLOCPP.CPP-A first C++ program. 

#i nc I u d e <i ostream. h> 

// Stock C++ hello program 

void ma i n ( ) 

{ 

c o lit << "Hello wo r I d , this is C++\ n " ; 

} 
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Only two linesin H ELLOCPP.CPP aredifferent from a standard C program. 
The first line differs because the include file, iostream.h, is a new concept to C 
programmers. The header file iostream.h accesses C ++'s standard I/O functions. 
Thesefunctions are similar to C'spr i ntf ( ) andscanf ( ) , and the header file is much 
like st di oh, which mostC programs include. 

T he line that prints the message to the screen is the other difference: 

co lit << "Hello wo r I d , this is C++\ n " ; 

Thislinemay seem strange to theC programmer. It doesn't appear to takethe 
form of a function call, yet it gets the message to the screen, as if by magic! To the C 
programmer, using the right shift operator seems to be wrong as well. 

C ++ has slightly different I /O facilities. Known as streams (the same as in C), 
these facilities have descriptive names, as shown in Tabled. 



Tabled. C- 


h+ Standard streams. 


stream 


Description 


cout 


0 utput to the standard screen or 




console, asin C'sstdout . 


ci n 


1 nput from the standard keyboard 




or console, asin C'sstdi n. 


cer r 


0 utput to the error screen or 




console, asin C'sstderr . 




C haracters sent to the error 




screen cannot be redirected using 




I/O redirection. 



Also in thepreceding exampleline, you usethe<< operator differently from how 
it is defined in C, because with C++ you can redefine an operator's function. This 
redefinition is contextually significant: the meaning of the << operator when used 
with the stream functions is different from how it's used in some other context. With 
stream functions, the >> and << operators are insertion operators that tell C++ what 
is being sent to the screen or received from the keyboard. 
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In C, the comment delimiter is the characters/* and * / . C++ has introduced 
a new type of comment, in which all charactersfollowing// until the end of 
th e I i n e are treated asacomment.This type of com m en t doesn 't requi re an 
ending comment marker. 

This can create a problem if you're not careful how you use blanks in state 
mentsthat are part of mathematical equations. The following lines of code 
(i = j +k/ 1 ) will be improperly parsed by a C/C ++compiler that allowsthe 
// comment: 

i = j +k/ / * divide by I */ 1 ; 
+ 1 ; 

The intent of this code is that the comment runs to just before the/ * 
delimiter and the variable i , but what happens is the compiler produces: 

i = j + k + I ; 

because the / / characters started a C ++ single line comment that continues to 
the end of the line. This isn't what the programmer wants, however. Because 
the code is syntactically correct, no warning or error is generated, and the 
mistake probably won't be found for sometime- probably several hours after 
the product has been shipped. 

To avoid this sort of problem, always U92 spacesaround all operators, includ- 
ing comment operators, as in: 

i = j + k / / * divide by I */ I; 
+ 1 ; 

With the spaces, the above fragment compiles correctly, and the spaces make 
the source easier to read. 

Simply stated, C++accepts// as a delimiter for a single comment line, but it 
is easy to create the// comment operator in error if you are not careful. C++ 
also accepts/* */ for opening and closing comment lines. 
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U nlikeC , C ++isa morestrongly typed language. C -H-also requiresyou to fully 
usefunction prototypes. Function prototypes allow the compiler to check and ensure 
that all the types match. 

Listing C.2 is a slightly more complex program, EXAM PLC PP. It shows 
input, output, and a ford loop. With your understanding of c out and ci n, this 
program is self-explanatory. 

Listing C.2. EXAMP1.CPP- A C++ program with both input and output. 

#i n c I u d e <i ostream. h> 
void ma i n ( ) 

{ 

int nCount = 0; 

int nStart = 0; 

cout << "Enter a starting point:"; 

c i n >> n St a r t ; 

cout << "nCount \ n He x Decimal Octal \n"; 

for (nCount = nStart; nCount < nStart + 16; nCount + + ) 

{ 

cout << hex << nCount << ' \ t ' 
<< dec << nCount << ' \ t ' 
<< oct << nCount « ' \ n' ; 

} 

} 



The output of this program, where the starting point was 0, is shown in 
Figured. 

This program shows more of the C++ stream functions, including the method 
to change the output from decimal to hexadecimal and octal. With cout you can 
actually do formatted output, but doing so isn't a trivial matter. 
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Borland C++ 



File Edit Search Bun Compile Project Browse Options Window 



Help 




Figured. Output from EXAM PLC PP. 




Quick & Dirty: If you can't figure out how to program something in C++, 
simply do it in C. Then later, when you understand how to write the applica- 
tion in C ++, you can convert it. Reverting to C is acceptable when you are 
first learning how to program in C++, but first try it in C++ before going 
back to C . 



T he rest of this chapter covers some of C ++'s main features. 



Overloading Functions 

W hen you overload something, you expect it to break. C ++, however, enables you to 
overload functions without much risk of breakage. 
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What isoverloading? M any articles written about overloaded functions assume 
the reader understandsoverloading. But many readersdon'tbecauseit isn't an obvious 
concept. For example, you have a program written in C that has floating-point 
variables (do ub i es), short int variables, and i ong (32-bit) integer variables. You can 
assumethat in various places in your program you need to determine the maximum 
of each data type. W ith C , you must write a function for each data type, and when 
writing the code, be sure you call thecorrect function. If in error you call theinteger 
function to determine maximums and inadvertently passdoubi e parameters, things 
won't work well! 

W ouldn't it beniceto haveonegeneric, maximum function that handlesall three 
types? That simply isn't possible. The function must know the data type when you 
write it, not when it is called. 

C ++ gives you an alternative: you can have three functions, all with the same 
name, but different parameter types. T he C ++ compi ler looks at the parameters and 
selects the correct function for the data type. 

Listing C.3, EXAM P2.CPP, is a program that uses overloaded functions It 
shows a maximum function; however, you could choose any function that might use 
different parameter types with different calls. 

Listing C.3. EXAMP2.CPP - Program showing C++ function overloading. 

// Program EXAMP2.CPP, written 27 July 1 9 9 2 by Peter D. Hipson 
// Shows the use of overloaded functions. 

#i n c I ud e <i ostream. h> 

// A double, long, and an int max() function are defined. You can 
// also have others, such as char, float, and so on. 

double ma x ( d o u b I e a , double b ) ; 
int ma x ( i n t a , i n t b ) ; 

long ma x ( I ong a, long b); 

void ma i n ( ) 
{ 

i nt nVal uel = 0; 
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i nt 


nVal u e 2 


= 0 


1 ong 


1 Val u el 


= 0 


1 ong 


1 Va 1 u e 2 


= 0 


doubl e 


dVal u el 


= 0 


doubl e 


dVal ue2 


= 0 



c o u t << "Enter two integer values: "; 
c i n >> n V a I u e 1 >> n V a I u e 2 ; 

cout << "The max of " << nValuel << " and " << n V a I u e 2 
<< " is " << max( nVal uel, n V a I u e 2 ) << "\n"; 

cout << "Enter two long integer values: "; 

ci n >> I Val uel >> I Val u e 2 ; 

cout << "The max of " << I Val uel << " and " << I Val u e 2 
<< " is " << max ( I Val uel, I Val u e 2 ) << "\n"; 

cout << "Enter two floating point values: "; 

c i n >> d Va I u e 1 >> d V a I u e 2 ; 

cout << "The max of " << dValuel << " and " << d V a I u e 2 
<< " is " << max( dVal uel, d V a I u e 2 ) << "\n"; 

} 

double ma x ( 
double a, 
double b) 

{ 

if (a < b) 

{ 

return ( b) ; 

} 

else 
{ 

r et u r n( a ) ; 

} 

} 

continues 
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Listing C. 3. continued 



i n t ma x ( 

i nt a , 
i nt b) 

{ 

if (a < b) 

{ 

return ( b) ; 

} 

else 

{ 

return) a ) ; 

} 

} 

long ma x ( 
long a , 
long b) 

{ 

if (a < b) 

{ 

return ( b) ; 

} 

else 

{ 

r et u r n ( a ) ; 

} 

} 



Thisprogram enables you to call max( ) without considering whether you need 
to call the floating-point, integer, or long version of thefunction. 

Declaring Variables When Needed 

With C, you can declare a variable only at the beginning of a block. Your programs 
often end up declaring variables far from where they are used, making correlation 
between a variable and its usage difficult. 
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OneC++ feature enables you to declare a variable wherever it isneeded. In the 
program EXAM P3.C PP (in Listing C .4), an index that will be used in a f or ( ) loop 
is declared in thet or ( ) statement. 

Listing C. 4. EXAM P 3. CP P — Program showing variable declaration in a 
statement. 

// Program E X AMP 3 . CP P , written 27 July 1 9 9 2 by Peter D. Hipson 
// Shows the use of variable declarations when needed. 

# i n c I u d e <i ostream. h> 



void ma i n ( ) 



i nt nStart = 0; 

cout << "Enter a starting point:"; 
c i n >> n St a r t ; 

cout << "nCount \ n He x Decimal Octal \n"; 

// Here, you declare an integer, nCount, which is used as the 
// f o r ( ) statement's loop counter. The variable is actually 
/ / declared in the f o r ( ) loop s t a t e me n t . 

for (int nCount = nStart; nCount < nStart + 16; nCount + + ) 

{ 

cout << hex << nCount << ' \ t ' 
<< dec << nCount << ' \ t ' 
<< oct << nCount << ' \ n ' ; 

} 

} 
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In the program, then count variable is actually declared in thet or ( ) statement, 
where it is first used: 

for (int nCount = nStart; nCount < nStart + 16; nCount + + ) 

Thissequence makes it easier to construct loops and other blocks without plac- 
ing the block's variables in the program where they are obviously not used. 

Default F unction Argument Values 

When writing functions, you may often create a function that requires many of its 
parameters for some purposes, yet other calls need only the first few parameters. 

You also sometimes need functions that seem to have a variable number of 
arguments, and you don't want to code a parameter describing the number of 
arguments. 

Finally, somefunctions often use default values for some parameters. 1 1 is then 
uptotheprogrammertocodethesedefaultvaluesforeach call ofthefunction. H eaven 
forbid should oneof thedefaultschange: you'll bechanging each of thecall by hand— 
a long and tedious process. 

C++ provides a solution: specify default values for parameters. This process is 
simple, being done in the function's prototype. Listing C .5 is the EXAM P4.C PP 
program, which demonstrates how to implement default arguments to a function. 

Listing C. 5. EXAMP4.CPP - Program showing default values for 
arguments. 

// Program EXAMP4.CPP, written 27 July 1 9 92 by Peter D. Hipson 
// Shows the use of default values for functions arguments. 

#i n c I u d e <l i mi t s . h > 
#i nc I ude <f I oat . h> 
#i n c I ud e <i ostream. h> 

// Defined are a double, long, and an int max() function. You can 
// also have others, such as char, float, and so on. 

// In this version, you have four parameters and find the max of 

// the four. Because the minimum number of arguments is two, the final 
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// two arguments must default to a value that doesn't cause 
/ / error values. 



double ma x ( d o u b I e a, double b, double c = D B L _ Ml N , double d = 
DBL_ Ml N) ; 

i nt ma x ( i n t a, i nt b, int c = I N T _ Ml N , i nt d = 
I NT_ Ml N) ; 

long ma x ( I o n g a, long b, long c = L 0 N G_ Ml N , long d = 
L 0 N G _ Ml N) ; 

void ma i n ( ) 



{ 



i nt 


nVal 


uel 


= 0; 


i nt 


nVal 


u e 2 


= 0; 


i nt 


nVal 


ue3 


= 0; 


1 ong 


1 Val 


uel 


= 0; 


long 


1 Val 


u e 2 


= 0; 


1 ong 


1 Val 


ue3 


= 0; 


1 ong 


1 Val 


u e 4 


= 0; 


doubl e 


dVal 


uel 


= 0. 


doubl e 


dVal 


u e 2 


= 0. 



cout << "Enter three integer values: " ; 

cin >> nValuel >> n V a I u e 2 >> n V a I u e 3 ; 

cout << "The max of " << nValuel << 
" and " << nVal u e 2 << 
" and " << n V a I u e 3 << 

" is " << max( nVal uel, n V a I u e 2 , n V a I u e 3 ) << "\n"; 

cout << "Enter four long integer values: " ; 

cin >> I Val uel >> I Val u e 2 >> I Val u e 3 >> I Val u e 4 ; 

cout << "The max of " << I Val uel << 
" and " << I Val u e 2 << 
" and " << I Val u e 3 << 
" and " << I Val u e 4 << 

continues 
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Listing C. 5. continued 

" is " << 

ma x { 1 V a I u e 1 , I Va I u e 2 r I Va I u e 3 r I Va I u e 4 ) <<"\n"; 
c o u t << "Enter two floating point values: "; 

cin >> dValuel >> d V a I u e 2 ; 

cout << "The max of " << dValuel << " and " << d Va I u e 2 
< < " is " < < ma x ( d V a I u e 1 , d V a I u e 2 ) < < " \ n " ; 

} 

double ma x ( 
double a, 
double b , 
double c , 
double d) 

{ 

if (a >b&&a >c &&a >d) 

return ( a ) ; 
if ( b > a && b > c && b > d ) 

return ( b) ; 
i f ( c > a && c > b && c > d) 

return ( c ) ; 



return ( d ) ; 

} 

i n t ma x ( 

i nt a 
i nt b, 
i nt c , 
i nt d) 

{ 

if (a >b&&a >c &&a >d) 

{ 
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return ( a ) ; 
f ( b > a && b > c && b > d) 

return ( b) ; 
f ( c > a && c > b && c > d ) 

return ( c ) ; 

et u r n ( d ) ; 



} 



ong max( 

long a , 

long b, 

long c , 

long d) 



{ 



f ( a > b && a > c && a > d ) 

return ( a ) ; 
f ( b > a && b > c && b > d) 

return ( b) ; 
f ( c > a && c > b && c > d ) 

return ( c ) ; 

et u r n ( d ) ; 



} 



N otice this program incorporates function overloading as well. As shown, none 
of these C++ features are mutually exclusive. Any unused parameters default to the 
minimum value the data type can hold, which enables your maximum function to 
work correctly. That way, you'll never select an unused argument as the maximum- 
nothing can be smaller than the default values. 
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References 

In C, you can use a pointer to access a variable. Using a pointer allows a program to 
use a variable in two different ways, using different names. Pointers have their 
downside— theyareoften misunderstood, have the wrong value stored in them, and 
areawkward becauseyou musttryto remember whether you aredealing with apointer, 
the object it is pointing to, or an object's address. 

C ++ has a method that allows a variable to have more than one name. T he 
second name isn't a pointer (once defined, it can access only the variable by which it 
was defined), but is another way to access the variable's storage. 

EXAM P5.CPP, Listing C.6 is a program that shows the use of a reference 
variable in a C++ program. 

Listing C.6. EXAMP5.CPP - Program showing a reference variable. 

// Program EXAMP5. CPP, written 27 July 1 9 9 2 by Peter D. Hipson 
// Shows the use of reference variable, externally used as a 
// function's return value... 

#i n c I u d e <i ostream. h> 

// function max() returns a reference variable... 
i n t ma x ( i n t a , i n t b ) ; 

void ma i n ( ) 

{ 

i nt nVal uel = 0; 

i nt nVal u e 2 = 0; 

// Create a reference variable, which is not quite the same as a 
// pointer to the original variable, because there is no actual 
// pointer. A reference variable is mo re like a second name for 
// a variable, 
i n t &nRefl = nValuel; 

cout << "Enter two integer values: "; 
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c i n >> n V a I u e 1 >> n V a I u e 2 ; 

c o u t << "The max of " << nValuel << " and " << n V a I u e 2 
<< " is " << ma x ( n Re f 1 , n Va I u e 2 ) << "\n"; 

} 

i n t ma x ( 

i n t a , 
i nt b) 

{ 

if (a < b) 

{ 

return ( b) ; 

} 

else 

{ 

r et u r n( a ) ; 

} 

} 



Notice in thee out statement 

cout << "The max of " << nValuel << " and " << n V a I u e 2 
<< " is " << ma x ( n Re f 1 , n Va I u e 2 ) << "\n"; 

that it refers to the variable nva i uei using the reference variable n Ret 1. The effect is 
the same as you would get by using the name nvai uei . 

References as Return Values 

U si n g a refer en ce vari abl e as a retu rn val u e creates an i n teresti n g si tu ati on . I n th i s case, 
you can use the function's name on the left side (as an i va i ue) of an assignment 
operator. 

The EXAM P6.CPP program in Listing C.7 shows the effect of using a refer- 
ence variable as a return value. 
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Listing C. 7. EXAMP6.CPP - Program showing a reference variable. 

// Program EXAMP6.CPP, written 27 July 1 9 9 2 by Peter D. Hipson 
// Shows the use of reference variable, externally used as a 
// function's return value... 

#i n c I ud e <i ostream. h> 

// Defined is an int max() function. 

i n t n L i mi t = 0 ; 

// function max() returns a reference variable... 
int & ma x ( i n t a , i n t b ) ; 

void ma i n ( ) 

{ 

int nVal uel = 0; 

int nVal u e 2 = 0; 

// Create a reference variable, which is not quite the same as a 
// pointer to the original variable, because there is no actual 
// pointer. A reference variable is mo re like a second name for 
// a variable, 
int &nRefl = nValuel; 

cout << "Enter two integer values: "; 

cin >> nValuel >> n V a I u e 2 ; 

cout << "The max of " << nValuel << " and " << n Va I u e 2 
<< " is " << ma x ( n Re f 1 , n V a I u e 2 ) << "\n"; 

cout << "The value of nLimit is " << nLimit << "\n"; 

max( 0, 0) =99; 

cout << "The value of nLimit is " << nLimit << "\n"; 
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} 



nt & max( 

i nt a , 
i nt b) 



{ 



f (a < b) 



{ 



n L i mi t = b ; 
return ( n L i mi t ] 



} 

else 

{ 



n L i mi t = a ; 
return( nLi mi t; 



To better understand the effects of running this program, take a look at its 
output, shown in Figure C .2. 



[Inactive D:\ 



Enter two integer ualues: 12 3U 
The max of 12 and 34 is 34 
The ualue of nLinit is 34 
The ualue of nLinit is 99 




FigureC. 2. Output from EXAM P6.CPP. 
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N otice after the statement 

ma x ( 0 , 0 ) =99; 

was executed the value of nu mi t changed to 99. Only your creativity limits how 
you use this ability of C++. 

Classes 

C lasses are one of the most important elements of C ++. T hey enable you to use one 
of the most powerful features of the language— data object management. You might 
think of classes as an extension to C's user-defined types. In C, when defining a type 
(using typedef ), you can include only actual data objects in that type. N o checking 
takes place to find if correct values have been assigned to aC user-defined type. 

Using C++ classes gives you many advantages. These advantages, described in 
thefollowing section, are valuable in maintaining your application's data integrity. 

A class can have all the allowed data types within it, including other classes. 
Nesting classes is done much the same as you would nest typedef ■ d objects in C. 

A class has a constructor, a function called whenever a data object of that class 
is created. You may have more than one constructor, each of which must have a 
different number of parameters. T heconstructor is responsiblefor ensuring that each 
member of the class is properly initialized and that any initialization values passed 
to the constructor are valid. 

A class has a number of manipulation functions that you can useto storevalues 
in the class's members, retrieve member values, print, output, input, or otherwise 
manipulate its members. 

A class also has a destructor, a function called whenever the class object is about 
to be destroyed. This function can take care of housekeeping, such as freeing any 
allocated memory. 

Using a class requires you to determine, as well as you possibly can, what you 
will usefor membersin theclass. You never havea problem adding members as needed 
or writing class functions to access new members; however, planning ahead helps 
prevent unchecked changes that can cause problems. 
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Listing C.8, EXAM P7.CPP, is a program that creates a class based on the 
database example program CREATED B.C in Chapter 7, "C Structures." The 
CREATEDB.C program makes a database record for either a customer or a 
supplier. 

Listing C.8. EXAM P7.CPP - Program showing C++ classes. 

// Program EXAMP7.CPP, written 27 July 1 9 9 2 by Peter D. Hipson 
// Shows C + + classes, initialization, and so on. 

# i n c I u d e <string.h> // Used for strcpyl), str...(), etc. 

# i n c I u d e <i ostream. h> // C ++' s stream I/O header. 

// Define your class structure, similar to those 

// created in earlier chapters showing database techniques. 

#def i ne CUSTOMER_ RECORD 1 
#def i ne SUPPLI ER_ RECORD 2 

/* Define your structure for the customer database. */ 

class Cu s t o mer 

{ 

publ i c: 



Customer ( i nt nRecType, // The class constructor 
char * s z C u s t N a me , 
char * s z Add r , 
double dSal es) ; 

void Get Cus t o mer ( ) ; 

void Pri ntCusto me r ( ) ; // Print a customer's information 
-Cus t ome r ( ) ; / / Des t r uc t or 



C u s t o me r ( ) ; 



// 



The default constructor 



pri vat e: 



i n t n Rec o r d T y pe ; 

char szCustomerName[ 120] ; 

char s z Add r ess [ 12 0] ; 

double dCur r entSal es; 



continues 
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Listing C. 8. continued 



}; 

Customer::Customer() / / The class constructor, default values. 

{ 

nRecordType = CUSTOMERRECORD; 
s t r c p y ( s z C u s t o me r N a me , " - NONE- " ) ; 
s t r c py ( s z Add r es s , " ■ NONE " ) ; 
dCur r ent Sal es = 0.0; 

} 

Customer : : Customer( i nt nRecType, // The class constructor, explicit 

// values 

char * s z Cu s t Na me , 
char * s z Ad d r , 
double dSal es) 

{ 

nRecordType = nRecType; 
s t r c p y ( s z C u s t o me r N a me , szCust Name) ; 
s t r c py ( s z Add r es s , s z Add r ) ; 
dCurrentSales = dSales; 

} 

void Cus t ome r : : Get Cu st o mer ( ) 

{ 

char s z L i n e [ 2 ] ; // Used to store a NEWLINE for cin.getline 

// You get, fromthe console, the object's data values, using a simple 
/ / mu I t i I i ne f o r ma t : 

cout << "Enter '" << CUSTOMER_ RECORD << "' for a Customer '" << 

SUPPLI ER_ RECORD « "' for a suppl i er: "; 
c i n >> nRecordType; 

// Below you don't use cin, but cin.getline, which gets all 

// characters until the delimiting character (the optional third 

// character). If the deli mi ting character is omitted, a 

// newline is assumed. When getting input, cin.getline!) does not 

// retrieve mo re characters than the second parameter specifies, 

// taking into consideration the ending NULL for the string. 
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cin.getl ine(szLi ne, sizeof(szLine)); // discard NEWLINE from last 

/ / input. 

c o u t < < "Enter the n a me : " ; 

ci n. getl i ne( s z C u s t o me r N a me , si z e o f ( szCustomer Name) ) ; 

cout << "Enter the address: " ; 

cin.getl i ne( szAddress, sizeof(szAddress)); 

cout < < "Enter the sales: " ; 
cin >> dCurrentSales; 

} 

void Customer:: Pri ntCustomer() 

{ 

// You print the object's data values, using a simple 
/ / mu I t i I i n e f o r ma t : 

cout << "Type\t" << nRecordType << "\n" << 
"NameU" << szCustomerName << "\n" << 
"Address\t" << szAddress << "\n" << 
" Sal es: \ t " << dCurrentSales << "\ n" ; 

} 

Cust o mer : : ~C u s t o me r ( ) 

{ 

// Nothing done here. You don't have anything to do when the 
/ / object is destroyed. 

} 

void ma i n ( ) 
{ 

// The first object is initialized with the default values. 
C u s t o me r C u s t o me r 1 ; 

// The second object is initialized with explicit values. 
Customer Cu s t o me r 2 ( C USTOME R_ RECORD, "John Smith", "New York, NY 1 0 0 0 0 ", 
1 2 3 4.5); 

continues 
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Listing C. 8. continued 



Customerl. Pri ntCustomer(); 
c o u t << "\ n"; 

Customer2. Pri ntCustomer(); 
c o u t << "\ n"; 
Cust omer 2. Get Cust omer () ; 
c o u t << "\ n"; 

Customer2. Pri ntCustomer(); 
c o u t << "\ n"; 

} 



I n thisprogram, you first create a class. Then you tell thecompilertheclassname 
and describe theclass: 

class C u s t o me r 

{ 

Following specification of the class name, describe those members in theclass 
that areto bepublic. I f a member is public, you can access it from theactual program; 
if a member is private, you can access it only from a function of theclass. 

public: 

In the public section, declare two class constructors by overloading theclass 
constructor function. This way, you create a default constructor with no parameters 
and a constructor that initializes theclassto specified values. T hen declare a function 
to get, from the keyboard, theclass's data. You declarea function to print that data to 
the screen. You also create a class destructor. 

Both the constructor and the destructor are required in creating a class. If 
you don't need these functions, you still must create a function that does nothing. A 
class constructor always has the same name as the class. T he destructor also has the 
same name as the class, but is preceded by a ~ character. 



718 



Introduction to C++ 



cc c 
c cc 



Customer!); // The default constructor 

C u s t o me r ( i n t nRecType, // The class constructor 

char * s z C u s t N a me , 

char * s z Add r , 

double dSal es) ; 



void Get Cust omer ( ) ; 

void Pri ntCusto me r ( ) ; // Print a customer's information 
~Cus t o me r ( ) ; / / Des t r uc t o r 

W ell hidden from your actual program, in theprivatesection, aretheactual data 
obj ects f or th i s cl ass. You keep them hidden (by making them private) so the program 
cannot modify them directly, but instead can modify them only through a function 
of the class. 

You define each variable just as you define a structure in C. Any data type is 
permissible, including other classes. 

pri vat e: 

i n t n Rec o r d T y pe ; 
char szCustomerName[ 120] ; 
char sz Address! 120]; 
double dCur r entSal es; 

}; 

Oncetheclassisdefined,youmustprovidethefunctionsthatarepartoftheclass. 
You must define these functions after the definition of the class itself. 

T he first function you create is the class constructor that initializes the class's 
memberstodefaultvalues.Thesedefaultvaluescan beany that areappropriatefor both 
the data's type and the application. Like a class destructor, a class constructor has 
neither a return value type nor a return statement. 

Customer::Customer() // The class constructor, default values. 

{ 

nRecordType = CUSTOMER, RECORD; 
s t r c p y ( s z C u s t o me r N a me , "-NONE-"); 
s t r c py ( s z Add r ess , " - NONE " ) ; 
dCur r ent Sal es = 0.0; 

} 
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T he next function is also a constructor (done by overloading the constructor 
function) that allows your program to specify the values to assign to the class's 
members. 

Customer : : Customerf i nt nRecType, // The class constructor, explicit 

/ / values 

char * s z Cu s t Na me , 
char * s z A d d r , 
double d S a I es) 

{ 

nRecordType = nRecType; 
s t r c p y ( s z C u s t o me r N a me , szCust Name) ; 
s t r c py ( s z Add r es s , s z Add r ) ; 
dCurrentSales = dSales; 

} 

You next definetheclass function that gets, from thekeyboard, new values for 
the class's members. This function uses C ++'s c i n and ci n. get i i ne classes. Using 
ci n for numeric values is fine; however for character string values, ci n. geti i ne is 
better because it limits the number of characters assigned and ignores any white- 
space characters in the input string. Class functions, other than constructors and 
destructors, can have return values. You can use these return values to indicate 
either success or failure of the function, or to return a class member's value. 

void Cus t o me r : : Get Cu st omer ( ) 

{ 

char s z L i n e [ 2 ] ; // Used to store a NEWLINE for cin.getline 

// You get, fromthe console, the object's data values, using a simple 
/ / mu I t i I i ne f o r ma t : 

cout << "Enter '" << CUSTOME R_ RECORD « "' for a Customer "' << 

SUPPLI ER_ RECORD << for a supplier: " ; 
c i n >> nRecordType; 

// Below you don't use cin, but cin.getline, which gets all 

// characters until the delimiting character (the optional third 

// character). If the deli mi ting character is omitted, assume a 

// newline. When getting input, cin.getline!) does not 

// retrieve mo re characters than the second parameter specifies, 

// taking into account the ending NULL for the string. 
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cin.getl ine(szLi ne, sizeof(szLine)); // discard NEWLINE from last 

/ / input. 

c o u t < < "Enter the n a me : " ; 

c i n . g et I i ne ( s z Cu s t o me r Na me , si zeof( szCustomerName) ) ; 

cout << "Enter the address: " ; 

cin.getl i ne( szAddress, sizeof(szAddress)); 

cout << "Enter the sales: " ; 
cin >> dCurrentSales; 



} 



Thenext function printstheclass'scontentsto thescreen. You can also send the 
contents to a file, a communications port, and so on. This function is simple, using 
only cout to print. 

void Customer:: Pri ntCustomer() 

{ 

// You print the object's data values, using a simple 
/ / mu I t i I i n e f o r ma t : 



cout << "Type\t" << nRecordType << "\n" << 
"NarneU" << szCustomerName << "\n" << 
"Address\t" << szAddress << "\n" << 
" S a I e s : \ t " < < dCurrentSales < < " \ n " ; 

} 

The final function is the class destructor (which, like the constructor, is 
required). Because nothing must be done when the class object is destroyed, you 
simply return. Like a class constructor, a class destructor has neither a return value 
type nor a return statement. 



Cust o mer : : -Cust o mer ( ) 

{ 

// Nothing done here. You don't have anything to do when the 
/ / object is destroyed. 

} 

Once you are skilled at using classes, you will find these features helpful. Pro- 
per use of class objects limits the potential for program errors by requiring accessing 
and modifying class members by using an interface layer of functions that perform 
error checks. 



721 




unction/H eader File 
r oss Reference 

T h e prototypef or each function isin oneor moreheader files. T hefollowingtablelists 
the header filers), whether the function is AN SI, and the function's prototype. 

If thecolumn labeled ANSI has no entry, thefunction is not part of the AN SI 
standard. M any compilersmay offer thisfunction; however, you must carefully check 
whether a given compiler supports the function as you expect. 

Table D.l. H eader/ Function Cross Reference. 

Header file(s) ANSI Function prototype 

process.h & stdlib.h ANSI abortf ) 

math.h & stdlib.h ANSI abs( ) 

continues 
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Table D.l. continued 


Header file(s) 


ANSI 


Function prototype 


io.h 




access! ) 


math.h 


ANSI 


acos ( ) 


math.h 




acos 1 ( ) 


malloc.h 




a 1 1 o c a ( ) 


timeh 


ANSI 


a s c t i me ( ) 


math.h 


ANSI 


as i n ( ) 


math.h 




as i n 1 ( ) 


assert, h 


ANSI 


assert! ) 


math.h 


ANSI 


at a n ( ) 


math.h 


ANSI 


a t a n 2 ( ) 


math.h 




a t a n 2 1 ( ) 


math.h 




at a n 1 ( ) 


stdlib.h 


ANSI 


at ex i t ( ) 


math.h & stdlib.h 


ANSI 


atof ( ) 


stdlib.h 


ANSI 


at oi ( ) 


stdlib.h 


ANSI 


atol ( ) 


math.h & stdlib.h 




atol d( ) 


malloc.h 




be a 1 1 oc ( ) 


malloc.h 




bexpand( ) 


malloc.h 




b ma 1 1 o c ( ) 


malloc.h 




br ea 1 1 oc ( ) 


malloc.h 




bfree( ) 


malloc.h 




bf r eeseg ( ) 


malloc.h 




bhea p a d d ( ) 
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Header file(s) 



malloc.h 
malloc.h 
malloc.h 
malloc.h 
malloc.h 
malloc.h 

search. h & stdlib.h 

math.h 

math.h 

malloc.h & stdlib.h 

math.h 

math.h 

process.h 

conio.h 

conio.h 

direct.h 

direct.h 

io.h 

io.h 

float.h 

stdio.h 

timeh 

io.h 

io.h 

float.h 



AN SI 



ANSI 



ANSI 
ANSI 



ANSI 
ANSI 



Function prototype 



bheapchk( ) 
b heap mi n( ) 
bheapsegl ) 
bheapset ( ) 
b h e a p wa I k ( 
b ms i z e ( ) 
b s e a r c h ( ) 
cabs( ) 
cabsl ( ) 
c a I I o c ( ) 
cei I ( ) 
cei I I ( ) 
cexi t ( ) 
cget s( ) 
cget s( ) 
chdi r ( ) 
c h d r i v e ( ) 
c h mo d ( ) 
chsi ze( ) 
cl ea r 8 7 ( ) 
c I e a r e r r ( ) 
c I o c k ( ) 
close( ) 
c o mmi t ( ) 
c o n t r o I 8 7 ( 



continues 
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Table D.l. continued 



Header fi Ids) 


ANSI 


Function nrototvnp 

1 UIILLIUII Ml UIUIVmC 


main.n 


A M CI 
AN ol 


cos( ) 


rnatn.n 


A M CI 
AN ol 


cos h ( ) 


math.h 




cos h 1 ( ) 


math.h 




cosl ( ) 


conio.h 




cpr i ntf ( ) 


conio.h 




cput s( ) 


io.h 




cr eat ( ) 


conio.n 




c s c a n f ( ) 


UlIlc.M 


A M CI 
AIM 51 


c t i me ( ) 


m atn . n 




di eeetomsbi n( ) 


time.h 


A M CI 
AN ol 


J ■ £ £ L ' 1 V 

d i f f 1 1 me ( ) 


seal i d. n 


A M CI 

AN bl 


di v( ) 


rnatn.n 




dmsbi ntoi eee( ) 


io.h 




dup( ) 


io.h 




d u p 2 ( ) 


SLUM u. n 




ec v t ( ) 


io.h 




eof ( ) 


process, n 




exec 1 ( ) 


process, h 




exec 1 e( ) 


process, h 




exec 1 p( ) 


process, h 




exec 1 pe( ) 


process, h 




execv( ) 


process, h 




execve( ) 


process, h 




execvpl ) 
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Header file(s) 



process, h 

process.h & stdlib.h 

math.h 

malloc.h 

math.h 

math.h 

math.h 

stdlib.h 

malloc.h 

stdio.h 

stdio.h 

stdlib.h 

stdio.h 

stdio.h 

stdio.h 

malloc.h 

stdio.h 

malloc.h 

stdio.h 

stdio.h 

stdio.h 

stdio.h 

malloc.h 

malloc.h 

malloc.h 



AN SI 



ANSI 
ANSI 



ANSI 



ANSI 
ANSI 



ANSI 
ANSI 

ANSI 

ANSI 

ANSI 
ANSI 



D- 



Function prototype 



execvpe( ) 
exi t ( ) 
exp( ) 
expand! ) 
expl ( ) 
f a bs ( ) 
f absl ( ) 
f atexi t( ) 
f c al I oc ( ) 
f c I os e( ) 
f c I o s ea I I ( 
fcvt( ) 
f d o p e n ( ) 
f eof ( ) 
f e r r o r ( ) 
f expand! ) 
ff I u s h ( ) 
ffree( ) 
f get c { ) 
f get c ha r ( ) 
f get pos ( ) 
f get s ( ) 
f hea pc h k ( ) 
f h e a p mi n ( ) 
f heapset ( ) 



continues 
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Table D.l. continued 



n caller TllclaJ 


AN 


ruiiLiiuii piuiuiypc 


malloc.h 




f hea pwa 1 k( ) 


math.h 




fi eeetomsbi n( ) 


stdio.h 




f i 1 buf ( ) 


io.h 




f i 1 el engt h( ) 


stdio.h 




f i 1 e n o ( ) 


math.h 


A M CI 

AN bl 


floor( ) 


math.h 




f 1 oor 1 ( ) 


stdio.h 




f 1 s buf ( ) 


stdio.h 




£ 1 ...U.I 1 / \ 

f 1 us hal 1 ( ) 


manoc.n 




f ma 1 1 o c ( ) 


d-Hlih h 

SLUM u. n 




f mb 1 e n ( ) 


slum d. n 




f mbs t owe s ( ) 


d-Hlih h 

scuiiD.n 




f mbt owe ( ) 


memory.n cx siring. n 




f me mc c p y ( ) 


memory.n cx siring. n 




f me mc h r ( ) 


memory.h & string. h 




f me mc mp ( ) 


memory.h & string. h 




f memc py ( ) 


memory.h & string. h 




f me mi c mp ( ) 


string.h 




f me mmov e ( ) 


memory.h & string.h 




f memset ( ) 


math.h 


ANSI 


f mo d ( ) 


math.h 




f mo dl ( ) 


math.h 




fmsbi ntoi eee( ) 


malloc.h 




f ms i z e ( ) 
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Header file(s) 


AN SI 


Function prototype 


stdlib.h 




f onexi t ( ) 


stdio.h 


ANSI 


f o pe n ( ) 


float.h 




f p r e s et ( ) 


stdio.h 


ANSI 


f pri ntf ( ) 


stdio.h 


ANSI 


f put c { ) 


stdio.h 




f put char ( ) 


stdio.h 


ANSI 


f put s ( ) 


stdio.h 


ANSI 


freadl ) 


malloc.h 




f r e a 1 1 o c ( ) 


malloc.h & stdlib.h 


ANSI 


f r ee( ) 


malloc.h 




f r eec t ( ) 


stdio.h 


ANSI 


f r eo pen ( ) 


math.h 


ANSI 


f r ex p ( ) 


math.h 




f r expl ( ) 


stdio.h 


ANSI 


f scant ( ) 


stdio.h 


ANSI 


f seek( ) 


stdio.h 


ANSI 


f s et pos ( ) 


stdio.h 




f s o p e n ( ) 


string.h 




f s t r c a t ( ) 


string.h 




fstrchrl ) 


string.h 




f s t r c tnp ( ) 


string.h 




f st r c py ( ) 


string.h 




f s t r c s pn ( ) 


string.h 




f st r d u p ( ) 


string.h 




f s t r i c mp( ) 



continues 
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Table D.l. continued 


H mrJpr filpfc) 
n cmia imc\3/ 


ANSI 


rUllLLIUIl piuLULypc 


string. h 




f s t r 1 en ( ) 


string. h 




f s t r 1 wr ( ) 


string. h 




f st r neat ( ) 


string. h 




f st r ncmp( ) 


string. h 




f st r n c p y ( ) 


string. h 




f s t r n i c mp ( ) 


string. h 




f st r nset ( ) 


string. h 




f st r pbr k( ) 


string. h 




fstr rchr ( ) 


string. h 




f s t r r e v ( ) 


string. h 




f s t r s et ( ) 


string. h 




f s t r s pn ( ) 


string. h 




fstrstr) ) 


string. h 




fstrtok) ) 


string. h 




f s t r u p r ( ) 


stdio.h 


AN SI 


f tel 1 ( ) 


scant). n 




f ul 1 pat h ( ) 


stdh b.h 




f wc s t ombs ( ) 


stdlib.h 




f wc t o mb ( ) 


stdio.h 




f wo p e n ( ) 


stdio.h 


ANSI 


f wr i t e ( ) 


stdlib.h 




gcvt ( ) 


stdlib.h 




gcvt ( ) 


stdio.h 


ANSI 


get c ( ) 
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Header file(s) 



conio.h 

stdio.h 

conio.h 

direct.h 

direct.h 

direct.h 

stdlib.h 

process, h 

stdio.h 

stdio.h 

timeh 

malloc.h 

malloc.h 

malloc.h 

malloc.h 

malloc.h 

malloc.h 

malloc.h 

math.h 

math.h 

conio.h 

conio.h 

ctypeh 

ctypeh 

ctypeh 



AN SI 



ANSI 



ANSI 



ANSI 



ANSI 
ANSI 



Function prototype 



getch( ) 
get c ha r ( ) 
g et c h e ( ) 
g et c wd ( ) 
getdcwd( ) 
get d r i ve( ) 
g et e n v ( ) 
get pi d( ) 
gets( ) 
get w( ) 
g mt i me ( ) 
hugehal I oc( 
h e a p a d d ( ) 
heapchk( ) 
heap mi n( ) 
heapset ( ) 
heapwal k( ) 
hfree( ) 
hypot ( ) 
hypot I ( ) 
i np{ ) 
i n pw( ) 
i sal n u m( ) 
i s a I p h a ( ) 
i s as c i i ( ) 



continues 
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Table D.l. continued 


H mrJpr filpfc) 
n caua imc\3/ 


ANSI 


rUllLLIUIl piuLULypc 


io.h 




i sat t y( ) 


ctype.h 


A M CI 

AN bl 


i s cnt r 1 ( ) 


ctype.h 




i s c s y m( ) 


ctype.h 




i s c s y mf ( ) 


ctype.h 


A M CI 

AN bl 


i s d i g i t ( ) 


ctype.h 


A M CI 

AN bl 


i s g r a p h ( ) 


ctype.h 


A M CI 

AN bl 


i si o we r ( ) 


ctypeh 


AN 51 


i s pr i nt ( ) 


ctypeh 


AN 51 


i s p u n c t ( ) 


ctypeh 


a ki n 

AN SI 


i s s p a c e ( ) 


ctypeh 


a ki n 

AN SI 


i s u p per ( ) 


ctypeh 


AN SI 


i sxdi gi t ( ) 


stahb.h 




i t o a ( ) 


math.h 




i 0( ) 


math.h 




j 01 ( ) 


math.h 




i 1( ) 


math.h 




j 11 ( ) 


math.h 




j n( ) 


math.h 




j nl ( ) 


con io.h 




kbhi t ( ) 


math.h & stdlib.h 


ANSI 


1 a b s ( ) 


math.h 


ANSI 


1 d e x p ( ) 


math.h 




1 dexpl ( ) 


stdlib.h 


ANSI 


1 d i v < ) 
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Header file(s) 


AN SI 


Function prototype 


search. h 




find) ) 


local e.h 


ANSI 


o c a 1 e c o n v ( ) 


tirneh 


ANSI 


o c a 1 t i me ( ) 


io.h 




o c k i n g ( ) 


math.h 


ANSI 


og( ) 


math.h 


ANSI 


o g i o ( ) 


math.h 




oglOl ( ) 


math.h 




ogl ( ) 


setjmp.h 


ANSI 


ongj mp( ) 


stdlib.h 




rotl ( ) 


stdlib.h 




r o t r ( ) 


search. h 




search! ) 


io.h 




seek( ) 


stdlib.h 




toa( ) 


stdlib.h 


ma k e p a t h ( ) 


malloc.h & stdlib.h 


ANSI 


ma 1 1 o c ( ) 


math.h 


ma t h e r r ( ) 


stdlib.h 


ANSI 


mbl en( ) 


stdlib.h 


ANSI 


mbst owcs( ) 


stdlib.h 


ANSI 


mbt owe ( ) 


malloc.h 


me ma v 1 ( ) 


memory.h & string.h 




me mc c p y ( ) 


memory.h & string.h 


ANSI 


me mc h r ( ) 


memory.h & string.h 


ANSI 


me mc mp ( ) 


memory.h & string.h 


ANSI 


me mc p y ( ) 



continues 
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Table D.l. continued 



Header file(s) 



ANSI 



Function prototype 



memory.h & string.h 

malloc.h 

string.h 

memory.h & string.h 

direct, h 

direct.h 

io.h 

timeh 

math.h 

math.h 

memory.h & string.h 

malloc.h 

malloc.h 

malloc.h 

malloc.h 

malloc.h 

malloc.h 

malloc.h 

malloc.h 

malloc.h 

malloc.h 

malloc.h 

string.h 

stddef.h 



ANSI 
ANSI 



ANSI 
ANSI 



ANSI 



me mi c mp ( ) 
me mma x ( ) 
memmove( ) 
me ms e t ( ) 
mk d i r ( ) 
mk d i r ( ) 
mktempl ) 
mk t i met ) 
modf ( ) 
modf I ( ) 
mo v e d a t a ( ) 
ms i z e ( ) 
nc a I I oc ( ) 
n e x p a n d ( ) 
n f reef ) 
nhea pc h k ( ) 
n h e a p mi n ( ) 
nhea pset ( ) 
nhea p wa I k ( ) 
n ma I I o c ( ) 
n ms i z e ( ) 
nr ea I I oc ( ) 
nst r d u p ( ) 
of f setof ( ) 
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Header file(s) 


AN SI 


Function prototype 


stdlib.h 




onexi t ( ) 


io.h 




o pen ( ) 


conio.h 




out p( ) 


conio.h 




out pw( ) 


stdio.h & stdlib.h 


ANSI 


per r o r ( ) 


math.h 


ANSI 


pow( ) 


math.h 




powl ( ) 


stdio.h 


ANSI 


pr i nt f ( ) 


stdio.h 


ANSI 


put c { ) 


conio.h 




p u t c h ( ) 


stdio.h 


ANSI 


put c ha r ( ) 


stdlib.h 




putenv( ) 


stdio.h 


ANSI 


puts( ) 


stdio.h 




put w( ) 


search. h & stdlib.h 


ANSI 


qsor t ( ) 


signal. h 


ANSI 


raise( ) 


stdlib.h 


ANSI 


r a n d ( ) 


io.h 




read( ) 


malloc.h & stdlib.h 


ANSI 


real 1 o c ( ) 


io.h & stdio.h 


ANSI 


r e mo v e ( ) 


io.h & stdio.h 


ANSI 


r enamel ) 


stdio.h 


ANSI 


r ewi n d ( ) 


direct.h 




r md i r ( ) 


stdio.h 




r mt mp ( ) 


stdlib.h 




rotl ( ) 



continues 
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Table D.l. continued 





ANSI 

nil «ji 


Funrtinn nrntntvnp 


stdio.h 


A M CI 

AN bl 


scanf ( ) 


stdhb.h 




sear c h e n v ( ) 


stdio.h 


A M CI 

AIM bl 


set b u f ( ) 


setjmp.h 


A hi CI 

AN 51 


set j mp( ) 


local e.h 


A M CI 

AN bl 


set 1 ocal e( ) 


io. n 




set model ) 


stdio.h 


A M CI 

AN bl 


set v b u f ( ) 


biyr idi .i i 


A M CI 
AIM 51 


signal! ) 


rnatn.n 


A M CI 
AN bl 


si n( ) 


math.h 


A M CI 
AN jl 


s i n h ( ) 


maui.n 




s i n h 1 ( ) 


maui.n 




s i n 1 ( ) 


stdio.h 




s n p r i nt f ( ) 


io.h 




s o p e n ( ) 


process, n 




s pa wn 1 ( ) 


process, n 




spawnl e( ) 


process, n 




spawnl p( ) 


process, h 




spawnl p e ( ) 


process, h 




spawnv( ) 


process, h 




spawnve( ) 


process, h 




spawnvpl ) 


process, h 




spawnvpe( ) 


stdlib.h 




s p 1 i t pa t h ( ) 


stdio.h 


ANSI 


spr i ntf ( ) 
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Header file(s) 


AN SI 


Function prototype 


math.h 


ANSI 


sqrt ( ) 


math.h 




sqrt 1 ( ) 


stdlib.h 


ANSI 


s r an d ( ) 


stdio.h 


ANSI 


sscanf ( ) 


malloc.h 




stackavai 1 ( ) 


float.h 




stat u s 8 7 ( ) 


string.h 


ANSI 


s t r c a t ( ) 


string.h 


ANSI 


strchr( ) 


string.h 


ANSI 


st r c mp ( ) 


string.h 




s t r c mpi ( ) 


string.h 


ANSI 


st rcol 1 ( ) 


string.h 


ANSI 


st r c p y ( ) 


string.h 


ANSI 


st rcspn( ) 


timeh 




strdate( ) 


string.h 




st r d u p ( ) 


string.h 


ANSI 


s t r e r r o r ( ) 


timeh 


ANSI 


s t r f t i me ( ) 


string.h 




s t r i c mp( ) 


string.h 


ANSI 


s t r 1 e n { ) 


string.h 




s t r 1 w r ( ) 


string.h 


ANSI 


s t r n c a t ( ) 


string.h 


ANSI 


s t r n c mp ( ) 


string.h 


ANSI 


st r nc py ( ) 


string.h 




st r n i c mp( ) 


string.h 




s t r n s et ( ) 



continues 
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Table D.l. continued 


u aaHer fWala) 
n cdUa lllc\3j 


AN ^1 

Mil SI 


ruiliuuil piULULypc 


string. h 


A M CI 

AN bl 


st r pbr k( ) 


string. h 


AN SI 


st r r chr ( ) 


string. h 




st r r ev( ) 


string. h 




st r set ( ) 


string. h 


Akin 

AN SI 


st r s p n( ) 


string. h 


AN SI 


strstr( ) 


timeh 




s t r t i me ( ) 


staiirj.n 


A M CI 

AN bl 


s t r t o d ( ) 


string. h 


A M CI 

AN bl 


st r t o k( ) 


stall b.h 


a ki n 

AN SI 


strtol ( ) 


staiirj.n 


A M CI 

AN bl 


s t r t o 1 d ( ) 


_1_ _| 1 ! |_ U 

stdlib.h 


« M pi 

AN SI 


st rt oul ( ) 


string. h 




st r u p r ( ) 


string. h 


AN SI 


s t r x f r m( ) 


stdlib.h 




swab( ) 


process.h & stdlib.h 


a ki n 

AN SI 


system! ) 


math.h 


ANSI 


t a n ( ) 


math.h 


ANSI 


t a n h ( ) 


math.h 




tanhl ( ) 


math.h 




tanl ( ) 


io.h 




tel 1 ( ) 


stdio.h 




tempnam( ) 
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Header fil e(s) 


AN SI 


Function prototype 


time.h 


ANSI 


t i me ( ) 


stdio.h 


ANSI 


t mp file( ) 


stdio.h 


ANSI 


t mpna m( ) 


ctypeh 




t oas c i i ( ) 


ctypeh & stdlib.h 


ANSI 


t o 1 o we r ( ) 


ctypeh & stdlib.h 


ANSI 


t oupper ( ) 


timeh 




t z s e t ( ) 


stdlib.h 




ill toa( ) 


io.h 




u ma s k ( ) 


stdio.h 


ANSI 


unget c( ) 


conio.h 




u nget c h ( ) 


io.h & stdio.h 




unlink( ) 


stdarg.h 


ANSI 


v a _ a r g ( ) 


stdarg.h 


ANSI 


va_end( ) 


stdarg.h 


ANSI 


v a _ s t a r t ( ) 


stdio.h 


ANSI 


v f p r i n t f ( ) 


stdio.h 


ANSI 


v pr i nt f ( ) 


stdio.h 




vsnpri ntf( ) 


stdio.h 


ANSI 


v s p r i n t f ( ) 


stdlib.h 


ANSI 


west ombs( ) 


stdlib.h 


ANSI 


wc t o mb ( ) 


io.h 




write( ) 


math.h 




y0( ) 



continues 
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Table D.l. continued 



Header file(s) ANSI Function prototype 

math.h yoi ( ) 

math.h yi( ) 

math.h yii ( ) 

math.h yn( ) 

math.h yni ( ) 
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A computer language would be 
ineffective if it did not offer a way 



ndex 



Symbols 



#(stringize operator), 622-623 
##(token paste operator), 624 
#@ (characterize operator), 623 
include statement, 166-167 
% format specifier, 614 
& operator, 66, 154 
" delimiter, 166 

* argv[ ] parameter, 100 

* envp[] parameter, 100 

* indirection operator, 69 
/Fa option, 437 

/Fc option, 437 
/Fl option, 437 
/F Pa option, 668 



/FPc option, 668 

/FPc87 option, 668 

/F Pi option, 669 

/FPi87 option, 669 

/Ox switch, 446 

IS option, 437 

<deNmiter, 166 

« operator, 154 

= (assignment operator), 643 

= operator, 74 

= equality operator, 643 

>delimiter, 166 

» operator, 154 

[...] field, 619 

\ (macro continuation operator), 622 
\n newline character, 29 
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~ operator, 154 

_ _DATE _ _macro, 637 

_ _ F I L E _ _macro, 638 

FILE identifier, 500 

_ isascii( c) macro, 504 
__LINE__macro, 638 
_ _LI N E_ _ identifier, 500 
__STDC __macro, 638 

T I M E _ _macro, 637 

_ _toascii(_c) macro, 504 
_fsopen() function, 269 
_tolower() function, 503 
_tolower(_c) macro, 504 
_toupper() function, 503 
_toupper(_c) macro, 504 
| operator, 154 
-operator, 154 
1.23 constants, 27 
1.23F constants, 27 
1.23L constants, 27 
123L constants, 26 
123U constants, 26 
123U L constants, 26 
16-bit programs, 658 
32-bit programs, 658-659 
80x86 
CPUs, 247 

instruction sets, 671-672 



abort() function, 517, 522 

abs() function, 522 

abstraction, 696 

accessing 
dBASE files, 468-473 
random strings, 252 
tree method, 321 



acos() function, 523 
ADDER.C program, 72-74 
AddRecordO function, 394 
addresses, I/O base, 296 
alignment of data, 636 
allocating 

arrays, 244-247 

dynamic memory, 227 

memory, 516 
alpha testing, 642 
Alternate M ath Package Library 

(mLIBCA.LIB), 668 
AN SI (American N ational Standards 

Institute), 4-5 
ARCADE. C program, 282-287 
archive file attribute, 250 
argc parameter, 100 
arguments, command line, 99-100 
Array parameter, 540, 544, 566 
ARRAY1.C program, 49-51 
ARRAY2.C program, 55-56 
arrays, 46 

allocating, 244-247 

as pointers, 55 

bounds, 648 

character, 56-58, 74-75 

declarations, 46-47 

definitions, 47-48 

index, 389 

indexing, 48, 52-54 

names, 68 

of pointers, 58-62 

of structures, 195, 200 

single-dimensional, 52 

structures of, 200-202 
ASC 1 1 character set, 680 
asctime() function, 523 
asin() function, 524 
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assembly language, 438 

calling C functions, 451, 455 

calling from C, 447 

inline, 669 

routine types, 437 
assert() function, 524 
assert() macro, 501, 650-652 
ASSERT. C program, 651 
assert.h header file, 501 
assignment operator (=), 643 
assignment within conditional 
expression warning, 643 
atan() function, 524 
atan2() function, 525 
atexit() function, 517, 525 
atof() function, 526 
atoi() function, 526 
atol() function, 526 
attributes, file 

archive, 250 

directory, 250 

hidden, 250 

normal, 250 

read only, 250 

system, 250 
auto keyword, 7 
automatic variables, 644 
Average() function, 32 

B 



B -tree technique, 392-395 
BADSTR.C program, 27-29 
balance, 393 

base 10 numbering system, 139-141 
base parameter, 527 
BASIC language, 437, 443 
baud rate divisor register (LSB), 300 



baud rate divisor register (M SB), 300 
bD ay variable, 471 
beta testing, 642 
bfHasMemo variable, 470 
bfVERSIO N variable, 470 
binary 

files, 251-252 

number system, 141-142 

searches, 386, 426, 383-384 
bitfields, 155-158 

in structures, 206-208 

storing, 208 
bit operators, 154-155 
bits, testing, 158 
_BLAN K identifier, 502 
blank flags, 81 
block comments, header, 16 
bM onth variable, 471 
Borland C++compiler, 682-686 

configuration options, 685 

EasyWin program, 682 

file conversion utility, 683 

help system, 683 

hot spot editor, 683 

IDE, 685 

import library generation tool, 683 

make facility, 684 

precompiled headers, 683 

reducing storage requirements, 682 

source code profiler, 683 

Turbo Debugger, 683 

UAE monitor, 683 

window-monitoring facility, 683 

Workshop program, 682 
bounds, array, 648 
break keyword, 8 
breakpoints 

memory, 655 

program, 655 
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bsearchO function, 384, 517, 527 
bsort() function, 384 
BTREE.C program, 395-415 
buffers, 90 

BufferSize parameter, 536 
bugs 

automatic variables, 644 
global variables, 644 
improper array bounds, 648 
macro side effects, 644 
misused operators, 643 
misused pointers, 649 
operator precedence, 645-648 
order of evaluation, 649 
unititialized variables, 643 
variable sizes and types, 645 

building programs, 181 

byD ecimalPlace member, 473 

bY ear variable, 470 

byLength member, 473 

bytes, 143 
deleted flag, 473 
record status, 473 
redundant, 670 
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c field, 607-608, 615 
C functions, calling, 450 
from assembly, 451, 455 
from FORTRAN, 462 
from Pascal, 462 
C language 
calling other languages from, 443, 
449-450 
assembly, 447 
FORTRAN, 449-450 



compilers, see compilers 

portability, 4 

power of, 4 

routine types, 437 

standards, 3 
C with classes, see C++ language 
C++ language, 695 

classes, 714-715 

declaring variables, 704-705 

default parameter values, 706 

overloading functions, 701-702 

reference variables, 710 

return values, 711 
C/C++ compiler, 686-690 

debugger, 687 

DIALOG, 687 

hot spot editor, 687 

IDE, 687, 690 

IMAGEDIT, 687 

import library generation tool, 687 

makefacility, 688 

online help system, 687 

precompiled headers, 687 

source code profiler, 687 

SPY, 687 

UAE monitor, 687 
C_TI M E category, 572 
CALLASM .ASM program, 439-440 
calling 
C functions, 450 
from assembly, 451, 455 
from FORTRAN, 462 
from Pascal, 462 
conventions, 671 
other languages 

21, 508 

CHAR MAX identifier, 21-22, 508 
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CHAR_M IN identifier, 21, 508 
character 

arrays, 56-58, 74-75 

constants, 26 

literals, 623 

string constants, 26 
Character parameter, 547-551 
CH ARACTER_FIELD identifier, 472 
characterize operator (#@), 623 
characters 

\n newline, 29 

ASCII, 680 

column definition, 472-473 

multi byte, 517 

newline, 251 

whitespace, 550 
chChar parameter, 558, 578, 586, 

597-598 
cin stream, 698 
classes, 714-715 
clearerr() function, 269, 528 
Clipper compiler, 468 
clock() function, 529 
close() function, 279 
code 

MS-DOS function, 456-461 
segments, 670 
source profilers, 672 
version, 470 

writing in multiple languages, 
435-436 
Code Builder compiler, 659 
Codeview debugger, 656 
column definition 

characters, 472-473 

records, 471 
combining languages, 435-436 



data type compatibility, 463-465 

naming considerations, 465 

problems, 462-463 
command line arguments, 99-100 
commands 

DOS DEBUG, 438 

DOS MODE, 301 

link, 165 

common subexpression optimization, 

666-667 
communications ports, 296-301 
C ompact memory model, 673 
Compare parameter, 527, 566 
compare^ ) function, 326 
compilers, 681 

Borland C++, 682-686 
configuration options, 685 
EasyWin program, 682 
file conversion utility, 683 
help system, 683 
hot spot editor, 683 
IDE, 685 

import library generation tool, 
683 

make facility, 684 
precompiled headers, 683 
reducing storage requirements, 
682 

source code profiler, 683 
Turbo Debugger, 683 
UAE monitor, 683 
window-monitoring facility, 683 
Workshop program, 682 
C/C++, 686-690 
debugger, 687 
DIALOG, 687 
hot spot editor, 687 
IDE, 687, 690 
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IMAGEDIT, 687 
import library generation tool, 
687 

make facility, 688 
online help system, 687 
precompiled headers, 687 
source code profiler, 687 
SPY, 687 

UAE monitor, 687 

Clipper, 468 

Code Builder, 659 

MicrowayN DP C/C++, 659 

minimums, 5 

optimization, 660-662 

QuickC for Windows, 690-692 
advantages, 690 
disadvantages, 691-692 

Watcom C/386, 438, 659, 692-694 

working processes, 621 

Zortech C/C++, 659 
compiling 

multifile programs, 164 

multiple source files, 162-163 
conditional preprocessor directives, 634 
console I/O, 280-281, 287 
const keyword, 7, 500 
const modifier, 25 
constants, 25 

character, 26 

character string, 26 

D BL_D I G , 506 

D BL_EPSI LO N , 506 

DBL_M ANT_DIG, 506 

DBL_M AX, 506 

D BL_M AX_10_EXP, 506 

D BL_M AX_EXP, 506 

DBL M IN, 506 



D BL_M I N_10_EXP, 506 
D BL_M I N_EXP, 507 
double-floating-point, 27 
entering, 21 
float-floating-point, 27 
FLT_D IG, 507 
FLT_EPSILON , 507 
FLT_M ANT_D IG, 507 
FLT_M AX, 507 
FLT_MAX_10_EXP, 507 
FLT_M AX_EXP, 507 
FLT_M IN, 507 
FLT_M I N 10 EX P, 507 
FLT_M IN_EXP, 507 
FLT_RAD IX, 507 
FLT_ROUNDS, 507 
int, 26 

LDBL_DIG, 507 
LD BL_EPSI LO N , 507 
LDBL_M ANT_DIG, 507 
LD BL_M AX, 507 
LD BL_M AX_10_EXP, 507 
LDBL_M AX_EXP, 508 
LDBL_M IN, 508 
LDBL_M IN_10_EXP, 508 
LDBL_M IN_EXP, 508 
long double-floating-point, 27 
long int, 26 
SEEK_CUR, 515 
SEEK_END, 515 
SEEK_SET, 515 
unsigned int, 26 
constructors, 714 
continue keyword, 8 
_CONTROL identifier, 502 
conventions, calling, 671 
conversions, data type, 45 



converting 

macros to strings, 622 

strings, 516 
Coprocessor Library (mLIBC7. LIB), 
668 

CopyltemO function, 395, 423 
cos() function, 529 
cosh() function, 530 
cout stream, 698 
cprintf() function, 281 
cputs() function, 281 
creat() function, 279 
CREATEDB.C program, 209-212 
creating 

character literals, 623 

dBASE files, 484, 493 

identifiers, 499 

libraries, 182 

nodes, 423 

root node, 420 

temporary work files, 256 
cscanf() function, 281 
ctime() function, 530 
ctypeh header file, 502-504 
_CUSTNAM E structure, 359 

D 



d field, 608, 615 
data 
alignment, 636 

B -tree storing technique, 392-395 
files, 321 

objects, see variables 
segments, packing, 670 
data types 
char, 20 



conversions, 45 
double, 20 
float, 20 
identifiers 
floating-point, 22-25 
inttype, 21-22 
int, 20 
modifiers 
long, 20 
short, 20 
unsigned, 20 
databases, 467-468 
DATE_FI ELD identifier, 472 
DB3HEADER structure, 483 
dBASE, 467 
accessing files, 468-473 
files 

creating, 484, 493 

reading, 474 

updating, 494 

version codes, 470 
interfacing with, 468 
main header structure, 469-470 
DBGSTRNG.C program, 652-654 
D BL_D I G constant, 506 
D BL_D I G identifier, 22 
D BL_EPSI LO N constant, 506 
D BL_EPSI LO N identifier, 23 
DBL_M ANT_DIG constant, 506 
DBL_M ANT_DIG identifier, 23 
DBL_M AX constant, 506 
D BL_M AX identifier, 23 
D BL_M AX_10_EXP constant, 506 
D BL_M AX_10_EXP identifier, 23 
D BL_M AX_EXP constant, 506 
D BL_M AX_EXP identifier, 23 
DBL_M IN constant, 506 
DBL_M IN identifier, 23 
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DBL_M I N _10_EXP constant, 506 
DBL_M IN_10_EXP identifier, 23 
DBL_M I N_EXP constant, 507 
DBL_M IN_EXP identifier, 23 
D BL_RAD IX identifier, 23 
DBL_ROUNDS identifier, 23 
D BREAD .C program, 474-482 
DBWRITE.C program, 484-493 
de-dup, 336 
DEBUG utility, 146 
debuggers 

Codeview, 656 

QuickC for Windows, 657 

services, 655-656 

Turbo Debugger, 657 

VIDEO, 657 

seealso, debugging 
debugging, 641-642 

alpha testing, 642 

assert() macro, 650-652 

beta testing, 642 

bugs 

automatic variables, 644 
global variables, 644 
improper array bounds, 648 
macro side effects, 644 
misused operators, 643 
misused pointers, 649 
operator precedence, 645-648 
order of evaluation, 649 
unititialized variables, 643 
variable sizes and types, 645 
rules, 649-650 
without debuggers, 652 
seealso, debuggers, 655-656 

decimal number system, 139-141 

declarations, 30-33 

declaring 



arrays, 46-47 

structures, 197 

variables, 704 
default keyword, 8 
^define directive, 625 
DEFINE.H header file, 179 
definedO operator, 624 
defines.h header file, 167 
defining 

arrays, 47-48 

macros, 625 

structures, 191 
definitions, 33-35 
Delete() function, 395 
deleted flag byte, 473 
DeleteltemO function, 395, 417, 
426-428 

DeleteRecordO function, 394 
delimiters 

", 166 

<, 166 

>, 166 

DEMO. FOR program, 441 
denominator parameter, 531, 552 
dependency lines, 184 
destructors, 714 
difftime() function, 531 
DIGIT identifier, 502 
dlntegral parameter, 562 
direct port I/O, 288-289 
direct video I/O, 667 
directives 

^define, 625 

#slif, 633 

#else, 632 

#endif, 633-634 

terror, 628 

ffl, 629-630 
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tffdef, 630-631 
*fndef, 631-632 
include, 629 
#line, 634-635 
#pragma, 635 
#undef, 637 

conditional preprocessor, 634 
directory file attribute, 250 
disk files 

fixed-field, 392 

indexes in, 390 
disk-based lists, 346 
displaying records, 386 
div() function, 531 
DLL register, 301 
DLM register, 301 
do keyword, 8 

DOS DEBUG command, 438 
DOS M ODE command, 301 
DOS Protected M ode I nterface 

(DPM I), 658 
DOS SORT utility, 322 
DOS/4G product, 658 
double 
data type, 20 
keyword, 8 
linked lists, 346-347 
double-floating-point constants, 27 
DPM I (DOS Protected M ode 

Interface), 658 
DUM P.C program, 146-150 
dup() function, 279 
dup2() function, 279 
d Value parameter, 523-524, 528-533, 

536, 541, 554, 562, 574-576, 

594-595 
dValuel parameter, 525 
dynamic memory, 345 



dynamic memory allocation, 227 
E 



eand E fields, 608-609, 617 

E2BIG value, 504 

EACCES value, 504 

EAGAIN value, 505 

EasyWin program, 682 

EBADF value, 505 

E DEAD LOCK value, 505 

EDLINE.C program, 257-266 

EDO M value, 505 

E EX I ST value, 505 

efficiency, program, 657-658 

El NVAL value, 505 

ElementSize parameter, 540, 544, 566 

#el if directive, 633 

#else directive, 632 

else keyword, 8 

EM FILE value, 505 

Emulator Library (mLIBCE. LIB), 668 

encapsulation, 696-697 

#endif directive, 633-634 

endtime parameter, 531 

ENOENT value, 505 

EN O EXEC value, 505 

ENOM EM value, 505 

ENOSPC value, 505 

entering constants, 21 

enum keyword, 8 

environments 

operating, 162 

protected-mode, 231 
eof() function, 279 
equality operator (=), 643 
ERANGE value, 505 
errno() function, 504 
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errno.h header file, 504-506 
terror directive, 628 
EXAM Pl.CPP program, 700 
EXAM P2.CPP program, 702-704 
EXAM P3.CPP program, 705 
EXAM P4.CPP program, 706-709 
EXAM P5.CPP program, 710-711 
EXAM P6.CPP program, 712-713 
EXAM P7.CPP program, 715-718 
excluding portions of the source code, 
629 

EXDEV value, 505 
execution stepping, 656 
exit() function, 532 
exp() function, 532 
extern keyword, 8, 40, 164 
external 
names, 6 

variables, 40, 171 
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ffidds, 609-610, 617 
fabs() function, 533 
families of functions 

printfO, 606-614 

scanf(), 614-619 
far identifier, 500 
far pointers, 17 
fclose() function, 269, 533 
fcloseallO function, 269 
fdopen() function, 268-269, 279 
feof() function, 269, 533 
ferror() function, 269, 534 
fflushj) function, 269, 534 
fgetcO function, 269, 535 
fgetchar() function, 269 
fgetposO function, 269, 535 



fgets() function, 269, 536 
field definition records, 471 
fields 
[...], 619 
bit, 155-158 
in structures, 206-208 
storing, 208 

c, 607-608, 615 

d, 608, 615 

eand E, 608-609, 617 
f, 609-610, 617 
flag, 471 

g and G, 610, 617 
i, 608, 616-617 
n, 610, 618 
o, 610-611, 615 
pand P, 611, 618 
s, 612, 618 
szColumnN ame, 472 
u, 612, 617 
xandX, 613-616 
file opening mode, 538 
filenames 
input, 112 
output, 112 
filenoO function, 269 
FILEON E.C program, 6 
filepointer parameter, 529 
files 
attributes 
archive, 250 
directory, 250 
hidden, 250 
normal, 250 
read only, 250 
system, 250 
binary, 251-252 
data, 321 
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dBASE 

accessing, 468-473 

creating, 484, 493 

reading, 474 

updating, 494 

version codes, 470 
disk 

fixed-field, 392 

indexes in, 390 
handles, 268-271, 280 
header, 497, 629 

assert.h, 501 

ctypeh, 502-504 

DEFINE. H, 179 

defines.h, 167 

errno.h, 504-506 

float.h, 506-508 

io.h, 508 

limits.h, 508-509 

localeh, 509-510 

malloc.h, 510 

math.h, 510 

memory.h, 511 

precompiled, 671 

PROTOTYP.H, 170, 180-181 

search. h, 511 

signal. h, 512 

stdarg.h, 513 

stddef.h, 515 

stdio.h, 515 

stdlib.h, 516-517 

string.h, 517 

timeh, 518 

TWO Fl LE.H , 178 

TYPED EF.H, 168-169, 180 

varargs.h, 518 

VARS.H, 169-170, 180 
I/O, 250-251 



include, 167 
defines.h header file, 167 
prototyp.h header file, 170 
typedef.h header file, 168-169 
vars.h header file, 169-170 

indexed, 321, 367, 383 

MAKE, 182-184 

map, 165 

merging, 321, 329, 343-344 
OBJ, 165 

purging, 321, 336, 341-344 

sorting, 322, 343-344 

source, 161 

stdaux, 273 

stderr, 272-273 

stdin, 271 

stdout, 272 

stdprn, 274 

stream, 268 

text, 251-252 

work, temporary, 256, 267-268 
FILETWO.C program, 6 
fixed-field disk files, 392 
FIXSTR.C program, 92-94 
flags 

blank, 81 

fidds, 471 

printf() family of functions, 607 
float data type, 20 
float keyword, 8 
float.h header file, 506-508 
FLO AT_FI ELD identifier, 473 
floating-point constants, 27 
floating-point optimization, 667-669 
floor() function, 536 
F LT_D I G constant, 507 
F LT_D I G identifier, 23 
F LT_E PSI LO N constant, 507 
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F LT_E PSI LO N identifier, 23 
FLT_M AN T_D IG constant, 507 
FLT_M AN T_D I G identifier, 24 
FLT_M AX constant, 507 
FLT_M AX identifier, 24 
FLT_M AX_10_EXP constant, 507 
FLT_MAX_10_EXP identifier, 24 
FLT_M AX_EXP constant, 507 
FLT_M AX_EXP identifier, 24 
FLT_M IN constant, 507 
FLT_M IN identifier, 24 
FLT_MIN_10_EXP constant, 507 
FLT_M I N_10_EXP identifier, 24 
FLT_M I N_EXP constant, 507 
FLT_M I N_EXP identifier, 24 
FLT_RAD IX constant, 507 
FLT_RAD IX identifier, 24 
FLT_ROUNDS constant, 507 
FLT ROU N DS identifier, 24 
flushallO function, 269 
fmod() function, 537 
fopen() function, 268-269, 537 
for keyword, 9 
format codes, 582-583 
format specifiers, 614 
__fortran keyword, 450 
FORTRAN keyword, 7 
FORTRAN language, 435, 441 

calling C functions, 462 

calling from C, 449-450 

routine types, 437 
fprintf() function, 538 
fputc() function, 269, 538 
fputchar() function, 269 
fputsO function, 269, 539 
freadO function, 269, 539 
free!) function, 235-237, 540 

M icrosoftC, 235 



rules, 236 
freopen() function, 268-269, 540 
frexpO function, 541 
fscanf() function, 269, 542 
fseek() function, 269, 542 
fsetposO function, 269, 543 
ftdlO function, 256, 269, 385, 544 
function/header cross reference table, 
723-740 

function codes, M S-DOS, 456-461 
functions 

_fsopen(), 269 

_tolower(), 503 

_toupper(), 503 

abort(), 517, 522 

abs(), 522 

acos(), 523 

AddRecordO, 394 

asctime(), 523 

asin(), 524 

assertO, 524 

atan(), 524 

atan2(), 525 

atexit(), 517, 525 

atof(), 526 

atoi(), 526 

atol(), 526 

Average(), 32 

bsearchO, 384, 517, 527 

bsort(), 384 

callocO, 232-235, 483, 528 
casein, 6 
ceN(), 528 
cgetsO, 281 
clearerrO, 269, 528 
clock(), 529 
closeO, 279 
compare^ ), 326 
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CopyltemO, 395, 423 


fputs(), 269, 539 


cosO, 529 


freadO, 269, 539 


cosh(), 530 


freeO, 235-237, 540 


cprintfO, 281 


M icrosoftC, 235 


cputs(), 281 


rules, 236 


creat(), 279 


freopen(), 268-269, 540 


cscanfO, 281 


frexpO, 541 


ctimeO, 530 


fscanf(), 269, 542 


DdeteO, 395 


fseek(), 269, 542 


Ddeteltem(), 395,417,426-428 


fsetposO, 269, 543 


DdeteRecordO, 394 


ftdlO, 256, 269, 385, 544 


difftime(), 531 


fwrite(), 270, 544 


div(), 531 


getc(), 270, 545 


dup(), 279 


getch(), 132, 280-281 


dup2(), 279 


getcharO, 270-271, 545 


eof(), 279 


getche(), 281 


errnoO, 504 


gets(), 270-271, 327, 546 


exit(), 532 


getw(),270 


exp(), 532 


GiveHdpO, 110 


fabs(), 533 


gmtime(), 546 


fclose(), 269, 533 


hallocO, 229 


fcloseallO, 269 


headers, 14 


fdopenO, 268-269, 279 


inp(), 288 


feof(), 269, 533 


input/output, 90 


ferrorO, 269, 534 


inpw(), 288 


fflush(), 269, 534 


InsertO, 395,420-421 


fgetcO, 269, 535 


intrinsic, 664-666, 672 


fgetcharO, 269 


isalnum(), 503, 547 


fgetposO, 269, 535 


isalphaO, 502, 547 


fgets(), 269, 536 


iscntrl(), 503, 547 


filenoO, 269 


isdigit(), 502, 548 


floor(), 536 


isgraph(), 503, 548 


flushallO, 269 


islower(), 502, 549 


fmod(), 537 


isprint(), 503, 549 


fopen(), 268-269, 537 


ispunct(), 502, 549 


fprintfO, 538 


isspace(), 502, 550 


fputcO, 269, 538 


isupper(), 502, 551 


fputcharO, 269 


isxdigitO, 502, 551 
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kbhito, 281 
labsO, 551 
IdexpO, 552 
ldiv(), 552 

localeconvO, 510, 553 
localtime(), 553 
log(), 554 
loglOO, 554 
longjmpO, 512, 554 
IseekO, 279 
main(), 100 
mallocO, 228-232, 556 

M icrosoftC, 228 

rules, 228 
maximumO, 445, 449 
mblen(), 556 
mbstowcsO, 557 
mbtowcO, 557 
memchrO, 511, 558 
memcmpO, 511, 558 
memcpyO, 511, 559 
memmove(), 511, 560 
memsetO, 511, 229, 561 
mktime(), 561 
modf(), 562 
modifying, 428 
NewltemO, 395, 423 
NumberWordsO, 78, 81 
offsetofO, 562 
open(), 279 
outp(), 288 

OutputDebugStringO, 655 
outpw(), 288 
overloading, 701-702 
parameters, 164, 574 
perror(), 563 

pointers, 114-115, 119-120 
pow(), 564 



printfO, 270-272, 564 
PrintHdpO, 395 
PrintTree(), 395 
prototypes, 164, 497-499, 723 
PullDownO, 133 
putc(), 270, 564 
putch(), 281 
putcharO, 270-272, 565 
puts(), 270-272, 565 
putw(), 270 

qsort(), 114, 246, 322,517, 566 
raise(), 566 
rand(), 516, 567 
read(), 279 

reallocO, 237-238, 243-244, 567 

remove(), 267, 568 

rename(), 568 

rewindO, 270, 568 

rmtmpO, 270 

scanf(), 270-271, 569 

SearchO, 395, 418-419 

SearchAndAddO, 395, 417-419 

Search RecordO, 395 

setbufO, 270, 569 

setjmpO, 512, 570 

setlocaleO, 509, 571 

setvbufO, 270, 572 

signalO, 573 

sin(), 574 

sinh(), 575 

sopen(), 279 

sprintO, 92 

sprintfO, 270, 575 

sqrt(), 576 

srand(), 516, 576 

sscanfO, 270, 576 

strcatO, 577 
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strchr(), 577 


va_, 600 


strcmpO, 75, 329, 578 


va arg(), 598 


strcollO, 579 


va startO, 601 


strcpyO, 29, 580 


vfprintf(), 271, 601 


strcspn(), 580 


vprintfO, 271-272, 602 


strerror(), 581 


vsprintfO, 271, 604 


strftime(), 581-583 


wcstombsO, 605 


stricmpO, 329 


wctombO, 606 


string, 90 


write(), 279 


strlenO, 583 


FUNPTR.C program, 115-117 


strncatO, 584 


fwrite() function, 270, 544 


strncmpO, 584 




strncpyO, 585 


G 


strpbrkO, 586 




strrchrO, 586 


gand G fields, 610, 617 


strspnO, 587 


getc() function, 270, 545 


strstr(), 588 


getch() function, 132, 280-281 


strtodO, 516, 588 


getchar() function, 270-271, 545 


strtokO, 589 


getche() function, 281 


strtoK), 516, 590 


gets() function, 270-271, 327, 546 


strtouK), 516, 591 


getw() function, 270 


strxfrmO, 592 


GiveH elp() function, 110 


switch(), 136 


global 


system(), 516, 593 


memory, 247 


tan(), 594 


scope, 31 


tanh(), 594 


variables, 644 


tdl(), 279 


gmtime() function, 546 


tempnamO, 270 


goto keyword, 9 


time(), 595 




tmpfile(), 256, 268-270, 596 


H 


tmpnamO, 256, 266, 270, 596 




tolowerO, 503, 597 


hallocO function, 229 


toupper(), 503, 597 


header/function cross reference table, 


TreePrintO, 395,424 


723-740 


UnderFlowO, 395,427 


header files, 497, 629 


ungetcO, 270, 597 


assert. h, 501 


ungetchO, 281 




unlinkO, 267 
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ctypeh, 502-504 

DEFINE. H, 179 

defines.h, 167 

errno.h, 504-506 

float.h, 506-508 

io.h, 508 

limitsh, 508-509 

localeh, 509-510 

malloc.h, 510 

math.h, 510 

memory.h, 511 

precompiled, 671 

PROTOTYP.H , 170, 180-181 

search. h, 511 

signal. h, 512 

stdarg.h, 513 

stddef.h, 515 

stdio.h, 515 

stdlib.h, 516 

communications with operating 
system, 516-517 

integer math, 517 

memory allocation, 516 

multibyte characters, 517 

random numbers, 516 

searches, 517 

string conversion, 516 
string.h, 517 
timeh, 518 
TWO Fl LE.H , 178 
TYPEDEF.H, 168-169, 180 
varargs.h, 518 
VARS.H , 169-170, 180 
headers 
block comments, 16 
functions, 14 
H ELLO.BAS program, 443 
HELLO. C program, 14-15 



H ELLO.PAS program, 442 

HELLOCPP.CPP program, 697 

_H EX identifier, 502 

hex number system, 142-144 

hidden file attribute, 250 

hierarchies, 697 

high-levd I/O, 278 

H uge memory model, 674 

H ungarian notation, 13 
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i field, 608, 616-617 
I/O (input/output), 249 

base address, 296 

console, 280-281, 287 

direct port, 288-289 

files, 250-251 

functions, 90 

high-levd, 278 

low-level, 278-280 

port, 280-281, 287 

video direct, 667 
identifiers 

Fl LE , 500 

_ LI N E_ _, 500 

_BLAN K, 502 

CH AR_BIT, 21, 508 

CH AR_M AX, 21-22, 508 

CHAR_MIN,21, 508 

CH ARACTER_FIELD, 472 

const, 500 

_CONTROL, 502 

creating, 499 
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D AT E_F I E L D , 472 

D B L_D I G , 22 

D B L_E PSI LO N , 23 

DBL_MANT_DIG, 23 

DBL_M AX, 23 

D BL_M AX_10_EXP, 23 

D BL_M AX_EXP, 23 

DBL_M IN, 23 

D BL_M I N_10_EXP, 23 

D BL_M I N_EXP, 23 

D BL_RAD IX, 23 

DBL_ROUNDS, 23 

_DIGIT, 502 

far, 500 

FLO AT_FI ELD , 473 
FLT_D IG, 23 
F LT_E PSI LO N , 23 
FLT_M ANT_D IG, 24 
FLT_M AX, 24 
FLT_MAX_10_EXP, 24 
FLT_M AX_EXP, 24 
FLT_M IN, 24 
FLT_M IN_10_EXP, 24 
FLT_M IN_EXP, 24 
FLT_RAD IX, 24 
FLT_ROUNDS, 24 
_HEX, 502 
I NT_M AX, 22, 509 
I NT_M IN , 22, 509 
LJmpnam, 266 
LC_ALL, 509 
LC_CO LLATE, 509 
LC_CTYPE, 509 
LC_M 0 N ETARY, 509 
LC_NUM ERIC, 510 
LC_TI M E, 510 
LD BL_D IG , 24 
LD BL_EPSI LO N , 24 



LDBL_M ANT_DIG, 24 
LDBL_M AX, 24 
LDBL_MAX_10_EXP, 25 
LD BL_M AX_EXP, 25 
LDBL_M IN, 25 
LDBL_M IN_10_EXP, 25 
LDBL_M IN_EXP, 25 
LD BL_RAD IX, 25 
LDBL_ROUN DS, 25 
LOGICAL_FIELD, 472 
LO N G_M AX, 22, 509 
LONG_M IN, 22, 509 
_LOWER, 502 
M B_LEN_M AX, 22, 508 
MEMO_FIELD,472 
NDEBUG, 501 
near, 500 

N U M ERIC_FIELD, 472 

PICTU RE_FIELD, 473 

_PUNCT, 502 

SCHAR_M AX, 21, 508 

SCHAR_M IN, 21, 508 

SH RT_M AX, 22, 509 

SH RT_M IN, 22, 508 

size_t, 500 

JPACE, 502 

string, 129 

testing, 630, 631 

UCH AR_M AX, 21, 508 

UINT_M AX, 22, 509 

ULONG_M AX, 22, 509 

_UPPER, 502 

USH RT_M AX, 22, 509 

volatile, 500 

see also, keywords, 7 

see also, macros, 621 

ffi directive, 629-630 

if keyword, 9 
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rtfdef directive, 630-631 
#fndef directive, 631-632 
in-memory data object, see indexed 
files, 321 

include directive, 629 
include files, see header files 
incrementing pointers, 67 
INDEX.C program, 368-382 
indexed files, 321, 367, 383 
indexes 

array, saving, 389 

in disk files, 390 
indexing 

arrays, 48, 52-54 

pointers, 89 
indirection, 65, 69 
initializing 

single-dimensional arrays, 52 

structures, 192 

variables, 15, 35-36 
inline assembly, 669 
inp() function, 288 
input filename, 112 
input/output (I/O), 249 

base address, 296 

console, 280-281, 287 

direct port, 288-289 

files, 250-251 

functions, 90 

high-level, 278 

low-level, 278-280 

port, 280-281, 287 

video direct, 667 
inpw() function, 288 
InsertO function, 395, 420-421 
insertion operators, 698 



instructions 

80x86 set, 671-672 

Int 21, 455 
Int 21 instruction, 455 
int constants, 26 
int datatype, 20 
int keyword, 9 

INT_M AX identifier, 22, 509 
INT_M IN identifier, 22,509 
integers 

overflow, 31 

storing, 151-154 

variables, 30 
Intel Code Builder product, 658 
interface cards, 288 
interfaces 

DPM I, 658 

user, 162 
interfacing with dBASE, 468 
interrupt enable register, 300 
interrupt identifier register, 300 
intrinsic functions, 664-666, 672 
io.h header file, 508 
IOFBF mode, 573 
IOLBF mode, 573 
IONBF mode, 573 
salnumO function, 503, 547 
salnum(_c) macro, 503 
salphaO function, 502, 547 
salpha( c) macro, 503 
scntrl() function, 503, 547 
scntrl( c) macro, 503 
sdigitO function, 502, 548 
sdigit( c) macro, 503 
sgraph() function, 503, 548 
sgraph(_c) macro, 503 
slower() function, 502, 549 



slower(_c) macro, 503 
sprint() function, 503, 549 
sprint( c) macro, 503 
spunct() function, 502, 549 
spunct(_c) macro, 503 
sspace() function, 502, 550 
sspace(_c) macro, 503 
supper() function, 502, 551 
supper(_c) macro, 503 
sxdigit() function, 502, 551 
sxdigit( c) macro, 503 
item structure, 416 

j-K 



jumpbuffer parameter, 555, 570 
JUSTIFY.C program, 103-109, 
136-137 



kbhit() function, 281 
key parameter, 527 
keywords 

auto, 7 

break, 8 

case, 8 

char, 8 

const, 7 

continue, 8 

default, 8 

do, 8 

double, 8 

else, 8 

enum, 8 

extern, 8, 40, 164 
float, 8 
for, 9 



FORTRAN, 7 

fortran, 450 

goto, 9 
if, 9 
int, 9 
long, 9 
PASCAL, 7 
register, 9 
reserved, 7-10 
return, 9 
short, 9 
signed, 7 
sizeof, 9 
static, 9 

struct, 9, 191-194 
switch, 10 
typedef, 10, 208 
union, 10 
unsigned, 10 
void, 10 
volatile, 7 
while, 10 

L 



L_tmpnam identifier, 266 
labs() function, 551 
languages 
assembly, 438 
calling C functions, 451, 455 
calling from C, 447 
inline, 669 
routine types, 437 
BASIC, 437, 443 
C 

calling other languages from, 443, 
447-450 
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compilers, sea compilers 

portability, 4 

power of, 4 

routine types, 437 

standards, 3 
C ++, 695 

classes, 714-715 

declaring variables, 704 

default parameter values, 706 

overloading functions, 701-702 

reference variables, 710 

return values, 711 
combining, 435-436 

data type compatibility, 463-465 

naming considerations, 465 

problems, 462-463 
FORTRAN, 435, 441 

calling C functions, 462 

calling from C, 449-450 

routine types, 437 
Pascal, 442 

calling C functions, 462 

calling from C, 449-450 

routine types, 437 
Large memory model, 674 
LC_ALL category, 572 
LC_ALL identifier, 509 
LC_CO LLATE category, 572 
LC_CO LLATE identifier, 509 
LC_CTYPE category, 572 
LC_CTYPE identifier, 509 
LC_MONETARY category, 572 
LC_M O N ETARY identifier, 509 
LC_NUM ERIC category, 572 
LC_NUM ERIC identifier, 510 
LC_TI M E identifier, 510 
LDBL DIG constant, 507 



LD B L_D I G identifier, 24 
LD BL_EPSI LO N constant, 507 
LD BL_EPSI LO N identifier, 24 
LDBL_M ANT_DIG constant, 507 
LDBL_M ANT_DIG identifier, 24 
LDBL_M AX constant, 507 
LD BL_M AX identifier, 24 
LDBL_MAX_10_EXP constant, 507 
LDBL_MAX_10_EXP identifier, 25 
LDBL_MAX_EXP constant, 508 
LD BL_M AX_EXP identifier, 25 
LDBL_M IN constant, 508 
LDBL_M IN identifier, 25 
LDBL_M IN_10_EXP constant, 508 
LDBL_M IN_10_EXP identifier, 25 
LDBL_M IN_EXP constant, 508 
LDBL_M IN_EXP identifier, 25 
LD BL_RAD IX identifier, 25 
LDBL_ROUNDS identifier, 25 
IdexpO function, 552 
ldiv() function, 552 
left side, 393 

IFieldPointer member, 473 
LIB utility, 182 
libraries, 165 

creating, 182 

mLIBC7.LIB,668 

mLIBCA.LIB, 668 

mLIBCE.LIB, 668 

reserved names, 10-11 
LIFETIM E.C program, 40-41 
limits.h header file, 508-509 
line control register, 301 
line dependency, 184 
#line directive, 634-635 
line numbers, modifying, 634 
line status register, 301 



linear searches, 345, 367, 383-384 
link commands, 165 
linked lists, 344-345 

disk-based, 346 

double, 346-347 

dynamic memory, 345 

linear searches, 367 
linking 

for performance, 670-671 

multifile programs, 164-165 

multiple source files, 162-163 
LI N KLIST.C program, 347-359 
list pointers, 346 

Listing 1.1. External name lengths for 

FILEONE.C and FILETWO.C, 6 
Listing 1.2. HELLO.C, 14-15 
Listing 1.3. A typical source file header 

block, 16-17 
Listing 2.1. BADSTR.C, 27-29 
Listing 2.2. An example of a global 

variable, in asinglesourcefile, 32 
Listing 2.3. An example of a global 

variable, in three source files, 33-34 
Listing 2.4. SCOPE.C, 37 
Listing 2.5. SCO PE1.C, 38-39 
Listing 2.6. LI FETIME.C, 40-41 
Listing 2.7. CASTS.C, 42-44 
Listing 2.8. ARRAY1.C, 49-51 
Listing 2.9. ARRAY2.C, 55-56 
Listing 2.10. REPEAT. C, 59-60 
Listing 3.1. POINTERS.C, 69-71 
Listing 3.2. The output from 

POINTERS.C, 72 
Listing 3.3. ADDER.C, 72-74 
Listing 3.4. NUM WORD. C, 76-77 
Listing 3.5. NUMWORD1.C, 79-81 
Listing 3.6. NUM WORD 3.COD, the 

assembly listing for the pointer version 



of NumberWords( ), 82-85 
Listing 3.7. NUMWORD4.COD, the 

assembly listing for the array indexed 

version of N umberWords( ), 85-89 
Listing 3.8. FIXSTR.C, 92-94 
Listing 3.9. RAGSTR.C, 95-96 
Listing 4.1. MAIN ARG S.C , 101-102 
Listing 4.2. J U ST I FY.C, 103-109 
Listing 4.3. FUNPTR.C, 115-117 
Listing 4.4.M EN Ul.C, 121-129 
Listing 4.5. State machine from 

JUSTIFY.C, 136-137 
Listing 5.1. DUM P.C, 146-150 
Listing 5.2. WCHBYTE.C, 152-153 
Listing 6.1. An example of a main 

include file for a large project, 167 
Listing 6.2. An example of the defines.h 

includefile, 167 
Listing 6.3. An exampleof the 

typedef.h includefile, 168-169 
Listing 6.4. An exampleof the vars.h 

includefile, 169-170 
Listing 6.5. An exampleof the 

prototyp.h includefile, 170 
Listing 6.6. TWO Fl LE1.C , 171-175 
Listing 6.7. TWOFILE2.C, 176-178 
Listing 6.8. TWOFILE.H, 178 
Listing 6.9. DEFINE. H, 179 
Listing 6.10. TYPEDEF.H, 180 
Listing 6.11. VARS.H , 180 
Listing 6.12. PROTOTYP.H , 180-181 
Listing 6.13.TWOFILE.MAK, a 

MAKE fileto compileTWO Fl LE, 

183 

Listing 6.14. TWO FILE, an advanced 
MAKE filefor theTWOFILE 
program, 184-186 

Listing 7.1. STRUCT1.C, 193-194 
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Listing 7.2. STRUCT2.C, 195-197 
Listing 7.3. STRUCTA.C, 198-199 
Listing 7.4. STRU CT3.C, 200-202 
Listing 7.5. STRU CT4.C, 203-205 
Listing 7.6. CREATEDB.C, 209-212 
Listing 7.7. OFFSETOF.C, 213-215 
Listing 7.8. STRU PTR.C, 216-219 
Listing 7.9. UN ION. C, 220-225 
Listing 8.1. MALLOC2.C, 230-231 
Listing 8.2. C ALLO C l.C , 233-235 
Listing 8.3. CD B.C, 238-243 
Listing 8.4. SO RT ALO C .C , 244-246 
Listing 9.1. TEXTFILE.C, 252-256 
Listing 9.2. ED LIN E.C, 257-266 
Listing 9.3. STDAUX.C, 273-274 
Listing 9.4. STD PRN .C, 275-276 
Listing 9.5. STD FILE. C, 276-278 
Listing 9.6. ARCAD E.C, 282-287 
Listing 9.7. PRN PORT.C, 289-295 
Listing 9.8. SENDCOM M .C, 301-308 
Listing 9.9. READ CO M M .C , 309-317 
Listing 10.1. SORTFILE.C, 323-326 
Listing 10.2. M ERGFILE.C, 330-334 
Listing 10.3. PURGFILE.C, 336-341 
Listing 10.4. LIN KLIST.C, 347-359 
Listing 10.5. IN DEX.C, 368-382 
Listing 10.6. BTREE.C, 395-415 
Listing 11.1. CALLASM .ASM, 
439-440 

Listing 11.2. DEMO. FOR, 441 
Listing 11.3. HELLO. PAS, 442 
Listing 11.4. HELLO. BAS, 443 
Listing 11.5. CALLN OTC.C, 443-446 
Listing 11.6. MAXIMUM. ASM, 
447-448 

Listing 11.7. The maximum() function 
in FORTRAN, 449 
Listing 11.8. MAXIM UM.C, 450-451 



Listing 11.9. CALLNOTC.ASM, 
452-455 

Listing 12.1. D BREAD .C, 474-482 
Listing 12.2. DBWRITE.C, 484-493 
Listing 13.1. VARGS.C, 513-515 
Listing 15.1. MACROS.C, 625-628 
Listing 16.1. ASSERT.C, 651 
Listing 16.2. DBGSTRNG.C, 652-654 
Listing C .1. H ELLO C PP.C PP— A first 

C++ program, 697 
Listing C .2. EXAM Pl.CPP-A C++ 

program with both input and output, 

700 

Listing C .3. EXAM P2.C PP- Program 
showing C ++ function overloading, 
702-704 

Listing C .4. EXAM P3.C PP- Program 
showing variable declaration in a 
statement, 705 

Listing C .5. EXAM P4.C PP- Program 
showing default values for arguments, 
706-709 

Listing C .6. EXAM P5.C PP- Program 
showing a reference variable, 710-711 
Listing C .7. EXAM P6.C PP- Program 
showing a reference variable, 712-713 
Listing C .8. EXAM P7.C PP- Program 
showing C ++ classes, 715-718 
lists, linked, 344-345 

disk-based, 346 

double, 346-347 

dynamic memory, 345 

linear searches, 367 
literals, character, 623 
IN umberRecords variable, 471 
local 

memory, 247 

scope, 31 
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Locale parameter, 571 
localeh header file, 509-510 
localeconv() function, 510, 553 
localtimeO function, 553 
lOffset parameter, 542 
log() function, 554 
loglOO function, 554 
LO G IC AL_FI ELD identifier, 472 
long double-floating-point constants, 
27 

long int constants, 26 

long keyword, 9 

long modifier, 20 

LO N G_M AX identifier, 22, 509 

LONG_M IN identifier, 22, 509 

longjmpO function, 512, 554 

loop optimization, 663-664 

low-level I/O, 278-280 

_LOWER identifier, 502 

LSB (baud rate divisor register), 300 

lseek() function, 279 

lvalue parameter, 552 

M 



machines, state, 135-136 

macro continuation operator (\), 622 

macros 

__DATE__, 637 

_ _FI LE _ _, 638 

_ isascii( c), 504 

_ LI N E _ _, 638 

__STDC __, 638 

__TIME__, 637 

_ toascii( c), 504 

_tolower(_c), 504 

_toupper(_c), 504 

assertO, 501, 650-652 



converting to strings, 622 
defining, 625 
isalnum(_c), 503 
isalpha( c), 503 
iscntrl( c), 503 
isdigit( c), 503 
isgraph( c), 503 
islower(_c), 503 
isprint( c), 503 
ispunct( c), 503 
isspace(_c), 503 
isupper( c), 503 
isxdigit( c), 503 
multiple line, 622 
NULL, 638 

offsetofO, 213-216, 515, 638 

redefining, 637 

side effects, 644 

tolower(_c), 504 

toupper(_c), 504 

see also, identifiers 
M ACROS.C program, 625-628 
main() function, 100 
MAINARGS.C program, 101-102 
MAKE files, 182-184 
mallocO function, 228-232, 556 

M icrosoftC, 228 

rules, 228 
malloc.h header file, 510 
MALLOC2.C program, 230-231 
managers, object library, 181-182 
map files, 165 
math.h header file, 510 
maximumO function, 445, 449 
MAXIMUM. ASM program, 447-448 
MAXIMUM.C program, 450-451 
M B_LEN_M AX identifier, 22, 508 
mblen() function, 556 
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mbstowcs() function, 557 
mbtowcO function, 557 
M edium memory model, 673 
M ember parameter, 563 
members 

byD ecimalPlace, 473 

byLength, 473 

IFieldPointer, 473 

nFirstRecordOffset, 484 
memchr() function, 511, 558 
memcmpO function, 511, 558 
memcpyO function, 511, 559 
memmove() function, 511, 560 
MEM OFI ELD identifier, 472 
memory 

allocation, 516 

breakpoints, 655 

dynamic, 227, 345 

global, 247 

local, 247 

models, 17-18, 673 

Compact, 673 

H uge, 674 

Large, 674 

M edium, 673 

Small, 673 

Tiny, 673 
memory modification, 655 
memory.h header file, 511 
memsetO function, 229, 511, 561 
M ENU1.C program, 121-129 
menus, relationship to pointers, 
120-121 

M ERG FILE. C program, 330-334 
merging files, 321, 329, 343-344 
message pragma, 635 
M icrosoft C 
callocO function, 232 



free() function, 235 
malloc( ) function, 228 
reallocO function, 237-238 

M icrosoft C/C++ compiler, 
see C/C++ compiler 

M icrosoft Windows 3.1, 658 

M icroway N DP C/C++ compiler, 659 

mktime() function, 561 

mLI BC 7.LI B (Coprocessor Library), 
668 

mLI BC A. LIB (Alternate M ath Package 
Library), 668 
mLI BC E.LI B (Emulator Library), 668 
M ode parameter, 537 
models, memory, 17-18, 673 

Compact, 673 

H uge, 674 

Large, 674 

M edium, 673 

Small, 673 

Tiny, 673 
modem control register, 301 
MODEM status register, 301 
modes 

file opening, 538 

IOFBF, 573 

IOLBF, 573 

IONBF, 573 
modf() function, 562 
modification 

memory, 655 

program, 656 
modifiers 

const, 25 

data type 
long, 20 
short, 20 
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unsigned, 20 

static, 40 
modifying 

functions, 428 

line numbers, 634 
modules, object, 181 
MS-DOS function codes, 456-461 
M SB (baud rate divisor register), 300 
mu I ti byte characters, 517 
multifile programs 

compiling, 164 

linking, 164-165 
multiline macros, 622 

N 



n field, 618 
n fields, 610 
names 

array, 68 

external, 6 

reserved library, 10-11 
n Base parameter, 591-592 
nBufferSize parameter, 581 
n Byte parameter, 561 
nChar parameter, 565 
nCharacter parameter, 539 
ncludefiles, see header files, 497 
nColumnCount variable, 483 
nConditional parameter, 524 
nCount parameter, 528, 557, 584-585, 
605 

nCurrentParameter variable, 112 
N DEBUG identifier, 501 
near identifier, 500 
near pointers, 17 
n Error parameter, 581 
nested testing, 633 



NewltemO function, 395, 423 
newline character, 251 
nException parameter, 566 
nExitC ode parameter, 532 
nExponent parameter, 541 
nFirstRecordOffset member, 484 
nFirstRecordOffset variable, 471 
nLength parameter, 558-561, 593 
nLineWidth variable, 113 
nM ode parameter, 572 
nN ewSize parameter, 567 
nodes, 393 

creating, 423 

root, 393, 420 
nOrigin parameter, 542 
normal file attribute, 250 
notation, H ungarian, 13 
nRecordLength variable, 471 
nReturnC ode parameter, 555 
nSeed parameter, 576 
nSignal parameter, 574 
nSize parameter, 528, 572 
NULL macro, 638 
NULL pointers, 345 
num parameter, 527 
number systems 

binary, 141-142 

decimal, 139-141 

hex, 142-144 

octal, 144-145 
N umberElements parameter, 540, 544, 
566 

numbers 

line, modifying, 634 

random, 516 
N umberW ords( ) function, 78, 81 
numerator parameter, 531, 552 
NUM ERIC_FI ELD identifier, 472 
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NUMWORD.C program, 76-77 
NUM WORD1.C program, 79-81 
NUMWORD3.COD program, 82-85 
NUMWORD4.COD program, 85-89 
nValue parameter, 522 



o fields, 610-611, 615 
OBJ files, 165 

object library managers, 181-182 
object modules, 181 
object-oriented programming (0 0 P), 
696 

abstraction, 696 

encapsulation, 696-697 

hierarchies, 697 
octal number system, 144-145 
offsetofO function, 562 
offsetofO macro, 213-216, 515, 638 
OFFSETOF.C program, 213-215 
offsets, 17 

one's complement operator (~), 157 
OOP (object-oriented programming), 
696 

abstraction, 696 

encapsulation, 696 

hierarchies, 697 
open() function, 279 
0 penFile parameter, 533-545, 565, 

569, 572, 598, 601 
operating environments, 162 
operators 

#(stringsize), 622-623 

## (token paste), 624 

#@ (characterize), 623 



&,66, 154 
*, 69 
<^ 154 
=,74 

= (assignment), 643 

= (equality), 643 

», 154 

\, 622 
154 

|, 154 

~, 154 

bit, 154-155 

definedO, 624 

insertion, 698 

precedence, 645-648 
optimization 

common subexpression, 666-667 

compiler, 660-662 

floating-point, 667-669 

loop, 663-664 
options 

/Fa, 437 

/Fc, 437 

/Fl, 437 

/FPa, 668 

/FPc, 668 

/FPc87, 668 

/FPi, 669 

/FPi87, 669 

IS, 437 
origin points 

SEEK_CUR, 543 

SEEK_END, 543 

SEEK_SET, 543 
OS/2 V 2 product, 658 
OS/386 product, 658 



outp() function, 288 
output filename, 112 
OutputDebugStringO function, 655 
outpw() function, 288 
overflow, integer, 31 
overlay programs, 670 
overloading functions, 701-702 

P 



p and P fields, 611, 618 
pack pragma, 636 
packing 

code segments, 670 

data segments, 670 

redundant bytes, 670 
_page structure, 416 
param parameter, 598, 601 
parameters, 498 

*argv[], 100 

*envp[], 100 

argc, 100 

Array, 540, 544, 566 
base, 527 
BufferSize, 536 
Category, 571 

Character, 547-549, 550-551 
chChar, 558, 578,586, 597-598 
Compare, 566 
compare, 527 
default values, 706 
denominator, 531, 552 



dlntegral, 562 

dValue, 523-524, 528-533, 536, 

541, 554, 562, 574-576, 594-595 
dValuel, 525 

ElementSize, 540, 544, 566 

endtime, 531 

filepointer, 529 

function, 574 

jumpbuffer, 555, 570 

key, 527 

Locale, 571 

lOffset, 542 

lvalue, 552 

M ember, 563 

M ode, 537 

nBase, 591-592 

nBufferSize, 581 

nByte, 561 

nChar, 565 

nC haracter, 539 

nConditional, 524 

nCount, 528, 557, 584-585, 605 

nError, 581 

n Exception, 566 

nExitCode, 532 

nExponent, 541 

nLength, 558-561, 593 

nM ode, 572 

nN ewSize, 567 

nOrigin, 542 

nReturnCode, 555 

nSeed, 576 

nSignal, 574 

nSize, 528, 572 

num, 527 

N umberElements, 540, 544, 566 
numerator, 531, 552 
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nValue, 522 

OpenFile, 533-545, 565, 569, 572, 

598, 601 
param, 598, 601 

pBuffer, 561,567-569, 572, 575 
pBufferl, 559 
pBuffer2, 559 
pDestination, 559-560 
pEnd, 588, 591-592 
pMuIti Byte, 557 
Pointer, 540 
Position, 535, 543 
previous, 601 
pSource, 559-560 
pWideChar, 557 
pWideCharacters, 605 
SizeToAllocate, 556 
startime, 531 
Structure, 563 

szBuffer, 536, 539, 546, 581, 604 
szCharacters, 586-588 
szChars, 580, 587 
szCommand, 594 
szDestination, 577, 580, 584-585, 

593, 605-606 
szFileName, 537, 541, 568, 596 
szFormat, 538, 542, 564, 569, 577, 

581, 601-604 
szlnput, 577 
szM ode, 541 
szN ewN ame, 568 
szOldName, 568 
szSource, 577, 580, 584-585, 593 
szString, 526-527, 556-558, 565, 

578-580, 583, 586-592 
szStringl, 578-579, 584 
szString2, 578-579, 584 
szTokenSep, 589 



Time, 562, 581 

TimeBuffer, 530 

TimeValue, 546, 553, 595 

type, 598 

VarArgs, 601-604 

WideChar, 606 

width, 527 

x, 537, 564 

y, 537, 564 
PASCAL keyword, 7 
Pascal language, 442 

calling C functions, 462 

calling from C, 449-450 

routine types, 437 
pBuffer parameter, 561, 567-569, 
572, 575 

pBufferl parameter, 559 
pBuffer2 parameter, 559 
pDestination parameter, 559-560 
pEnd parameter, 588, 591-592 
perror() function, 563 
Phar Lap 386/D O S-Extender product, 
658 

PICTU RE_FIELD identifier, 473 
pM ultiByte parameter, 557 
Pointer parameter, 540 
pointers, 66-68 

arrays as, 55 

arrays of, 58-62 

far, 17 

function, 114-115, 119-120 
incrementing, 67 
indexing, 89 
list, 346 
misusing, 649 
modifying variables, 72 
near, 17 
NULL, 345 
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relationship to menus, 120-121 

string, 95 

to structures, 216 
POINTERS.C program, 69-72 
points, origin 

SEEK_CUR, 543 

SEEK_SET, 543 
port I/O, 280-281, 287 
portability, 4 
ports 

communications, 296-301 

printer, 289, 295 
Position parameter, 535, 543 
pound symbol (#), 621 
pow() function, 564 
#pragma directive, 635 
pragmas 

message, 635 

pack, 636 
precedence, operator, 645-648 
precompiled header files, 671 
predefined actions 

SIG_ACK, 574 

SI G_D F L, 574 

SIGJGN, 574 
previous parameter, 601 
printer ports, 289, 295 
printf() family of functions, 606-614 
printf() function, 270-272, 564 
PrintHelpO function, 395 
PrintTree() function, 395 
PRNPORT.C program, 289-295 
profilers, source code, 672 
programming, OOP, 696 

abstraction, 696 

encapsulation, 696 

hierarchies, 697 
programs 



16-bit, 658 
32-bit, 658-659 
ADDER.C, 72-74 
ARCADE.C, 282-287 
ARRAY1.C, 49-51 
ARRAY2.C, 55-56 
ASSERT .C, 651 
BADSTR.C, 27-29 
breakpoints, 655 
BTREE.C, 395-415 
building, 181 

CALLASM .ASM , 439-440 
CALLNOTC.ASM, 452-455 
CALLNOTC.C, 443-446 
CALLOC1.C, 233-235 
CASTS.C, 42-44 
CDB.C, 238-243 
CREATEDB.C, 209-212 
DBGSTRNG.C, 652-654 
D BREAD .C, 474-482 
DBWRITE.C, 484-493 
DEMO. FOR, 441 
DUM P.C, 146-150 
EDLINE.C, 257-266 
efficiency, 657-658 
EXAM Pl.CPP, 700 
EXAM P2.CPP, 702-704 
EXAM P3.CPP, 705 
EXAM P4.CPP, 706-709 
EXAM P5.CPP, 710-711 
EXAM P6.CPP, 712-713 
EXAM P7.CPP, 715-718 
FILEONE.C, 6 
FILETWO.C, 6 
FIXSTR.C, 92-94 
FUNPTR.C, 115-117 
HELLO. BAS, 443 
HELLO.C, 14-15 
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HELLO. PAS, 442 
HELLOCPP.CPP, 697 
INDEX.C, 368-382 
JUSTIFY.C, 103-109, 136-137 
LIFETIM E.C, 40-41 
LIN KLIST.C, 347-359 
MACROS.C, 625-628 
MAINARGS.C, 101-102 
MALLOC2.C, 230-231 
MAXIMUM. ASM, 447-448 
MAXIMUM.C, 450-451 
M ENU1.C, 121-129 
M ERGFILE.C, 330-334 
modification, 656 
multifile 

compiling, 164 

linking, 164-165 
NUMWORD.C, 76-77 
NUMWORD1.C, 79-81 
NUM WORD3.COD, 82-85 
NUMWORD4.COD, 85-89 
OFFSETOF.C, 213-215 
overlay, 670 
POINTERS.C, 69-72 
PRN PORT .C, 289-295 
prototyping, 162 
PURGFILE.C, 336-341 
RAGSTR.C, 95-96 
READCOMM.C, 309-317 
REPEAT. C, 59-60 
SCOPE.C, 37 
SCOPE1.C, 38-39 
SENDCOMM.C, 301-308 
SORTALOC.C, 244-246 
SORTFILE.C, 323-326 
STDAUX.C, 273-274 
STDFILE.C, 276-278 
STDPRN.C, 275-276 



STRUCT1.C, 193-194 

STRUCT2.C, 195-197 

STRUCT3.C, 200-202 

STRUCT4.C, 203-205 

STRUCTA.C, 198-199 

STRUPTR.C, 216-219 

TEXTFILE.C, 252-256 

TWOFILE1.C, 171-175 

TWOFILE2.C, 176-178 

UNION.C, 220-225 

VARGS.C, 513-515 

WCHBYTE.C, 152-153 
protected -mode environments, 231 
protecting strings, 90-92 
PROTOTYP.H header file, 170, 
180-181 

prototypes, function, 164, 497-499, 
723 

prototyping programs, 162 
pSource parameter, 559-560 
PullDownO function, 133 
_PUNCT identifier, 502 
PURGFILE.C program, 336-341 
purging files, 321, 336, 341-344 
putc() function, 270, 564 
putch() function, 281 
putchar() function, 270-272, 565 
puts() function, 270-272, 565 
putw() function, 270 
pW ideC har parameter, 557 
pW ideC haracters parameter, 605 



Q 



qsort() function, 114, 246, 322, 517, 
566 

QuickC for Windows compiler, 
690-692 
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advantages, 690 
debugger, 657 
disadvantages, 691-692 

R 



ragged-right string arrays, 92 
RAGSTR.C program, 95-96 
raise() function, 566 
rand() function, 516, 567 
random numbers, 516 
read only file attribute, 250 
read() function, 279 
READCOMM.C program, 309-317 
reading dBASE files, 474 
reallocO function, 237-238, 243-244, 
567 

record status byte, 473 
records 

adding, 384-385 

column definition, 471 

displaying, 386 

field definition, 471 

retrieving, 386 
recursive, 114 
redefining macros, 637 
redundant bytes, packing, 670 
reference variables 

as return values, 711 

in C++, 710 
references, structure, 194 
register keyword, 9 
registers 

DLL, 301 

DLM , 301 

interrupt enable, 300 

interrupt identifier, 300 

line control, 301 



line status, 301 
LSB, 300 

modem control, 301 
MODEM status, 301 
MSB, 300 

removeO function, 267, 568 

rename() function, 568 

REPEAT. C program, 59-60 

reserved 
keywords, 7-10 
library names, 10-11 

retrieving records, 386 

return keyword, 9 

return values, 498 

rewindO function, 270, 568 

right side, 393 

rmtmpO function, 270 

root nodes, 393, 420 

S 



s field, 612, 618 
saving index arrays, 389 
scanf() family of functions, 614-619 
scanf() function, 270-271, 569 
SCHAR_M AX identifier, 21, 508 
SCH AR_M IN identifier, 21, 508 
scope, 37 

global, 31 

local, 31 
SCOPE.C program, 37 
SCOPE1.C program, 38-39 
scratch variables, 644 
SearchO function, 395, 418-419 
search. h header file, 511 
SearchAndAddO function, 395, 
417-419 
searches 
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binary, 383-386, 426 

linear, 345, 367, 383-384 
Search RecordO function, 395 
SEEK_CUR constant, 515 
SEEK CU R origin point, 543 
SEEK_EN D constant, 515 
SEEK_EN D origin point, 543 
SEEK_SET constant, 515 
SEEK_SET origin point, 543 
segments, 17 

code, 670 

data, 670 

SE N D C 0 M M .C program, 301-308 

serial boards, 296-300 

setbufO function, 270, 569 

setjmpO function, 512, 570 

setlocale() function, 509, 571 

sets, ASC 1 1 character, 680 

setvbuf() function, 270, 572 

shared variables, 164 

shells, 162 

short keyword, 9 

short modifier, 20 

SH RT_M AX identifier, 22, 509 

SH RT_M IN identifier, 22,508 

SIG_ACK predefined action, 574 

SI G_D F L predefined action, 574 

SIGJGN predefined action, 574 

SIGABRT value, 512 

SI G BREAK value, 512 

SIGFPE value, 512 

SI GILL value, 512 

SIGINT value, 512 

signalO function, 573 

signal. h header file, 512 

signed keyword, 7 

SIGSEGV value, 512 

SIGTERM value, 512 



sin() function, 574 
single-dimensional arrays, intializing, 
52 

sinh() function, 575 
size t identifier, 500 
sizeof keyword, 9 
SizeToAllocate parameter, 556 
Small memory model, 673 
sopen() function, 279 
sort/merges, 330 

SORTALOC.C program, 244-246 
SORTFILE.C program, 323-326 
sorting files, 322, 343-344 
source code profilers, 672 
source files, 161 

compiling, 162-163 

linking, 162-163 
_SPACE identifier, 502 
specifiers 

format, 614 

width, 112 
speed registers, 301 
spreadsheets, 467 
sprint() function, 92 
sprintf() function, 270, 575 
sqrt() function, 576 
srand() function, 516, 576 
sscanf() function, 270, 576 
starti me parameter, 531 
state 

machines, 135-136 

variables, 135 
statements 

include, 166-167 

typedef, 167 
static keyword, 9 
static modifier, 40 
static variables, declaring, 30 
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stdarg.h header file, 513 
stdaux file, 273 

STDAUX.C program, 273-274 

stddef.h header file, 515 

stderr file, 272-273 

ST D FILE. C program, 276-278 

stdin file, 271 

stdio.h header file, 515 

stdlib.h header file, 516 

communications with operating 
system, 516-517 

integer math, 517 

memory allocation, 516 

mu I ti byte characters, 517 

random numbers, 516 

searches, 517 

string conversion, 516 
stdout file, 272 
stdprn file, 274 

STDPRN.C program, 275-276 
stepping, 656 
storing 
bitfields, 208 

data, B -tree technique, 392-395 

integers, 151-154 
strcat() function, 577 
strchr() function, 577 
strcmpO function, 75, 329, 578 
strcollO function, 579 
strcpyO function, 29, 580 
strcspn() function, 580 
stream files, 268 
streams, 698 

cerr, 698 

cin, 698 

cout, 698 
strerror() function, 581 
strftimeO function, 581-583 



stricmpO function, 329 
string 

functions, 90 

identifiers, 129 

pointers, 95 
string.h header file, 517 
stringize operator (#), 622-623 
strings, 56-58, 74-75 

converting, 516 

converting from macros, 622 

protecting, 90-92 

ragged-right, 92 

random access, 252 
strlen() function, 583 
strncat() function, 584 
strncmpO function, 584 
strncpyO function, 585 
strpbrk() function, 586 
strrchr() function, 586 
strspn() function, 587 
strstr() function, 588 
strtodO function, 516, 588 
strtok() function, 589 
strtoK) function, 516, 590 
strtouK) function, 516, 591 
struct keyword, 9, 191-194 
STRUCT1.C program, 193-194 
STRUCT2.C program, 195-197 
STRUCT3.C program, 200-202 
STRUCT4.C program, 203-205 
STRUCTA.C program, 198-199 
Structure parameter, 563 
structure_name, 192 
structures, 191 

arrays of, 195, 200 

bitfields, 206-208 

_CUSTNAME,359 

DB3HEADER, 483 

declaring, 197 
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defining, 191 

initializing, 192 
item, 416 

of arrays, 200-202 

of structures, 203 

_page, 416 

pointers to, 216 

references, 194 
STRUPTR.C program, 216-219 
strxfrm() function, 592 
switch keyword, 10 
switch() function, 136 
system dependent, 231 
system file attribute, 250 
systemO function, 516, 593 
systems, number 

binary, 141-142 

decimal, 139-141 

hex, 142-144 

octal, 144-145 
szBuffer parameter, 536, 539, 546, 

581, 604 
szCharacters parameter, 586-588 
szChars parameter, 580, 587 
szColumnNamefield, 472 
szCommand parameter, 594 
szDestination parameter, 577, 580, 

584-585, 593, 605-606 
szFileN ame parameter, 537, 541, 

568, 596 

szFormat parameter, 538, 542, 564, 

569, 577, 581, 601-604 
szlnput parameter, 577 
szM ode parameter, 541 

szN ewN ame parameter, 568 
szO IdN ame parameter, 568 
szSource parameter, 577, 580, 

584-585, 593 
szString parameter, 526-527, 556-558, 



565, 578-580, 583, 586-592 
szStringl parameter, 578-579, 584 
szString2 parameter, 578-579, 584 
szTokenSep parameter, 589 



tag_name, 192 
tan() function, 594 
tanh() function, 594 
tdl() function, 279 
tempnamO function, 270 
temporary 

variables, 663 

work files, 256, 267-268 
testing 

alpha, 642 

beta, 642 

bits, 158 

identifiers, 630-631 

nested, 633 
text files, 251-252 
TEXTFILE.C program, 252-256 
Time parameter, 562, 581 
timeO function, 595 
timeh header file, 518 
TimeBuffer parameter, 530 
TimeValue parameter, 546, 553, 595 
Tiny memory model, 673 
tmpfile() function, 256, 268-270, 596 
tmpnamO function, 256, 266, 270, 
596 

token paste operator (##), 624 
tolower() function, 503, 597 
tolower(_c) macro, 504 
toupper() function, 503, 597 
toupper(_c) macro, 504 
transmit buffer, 300 
tree access method, 321 
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TreePrintO function, 395, 424 
truncation, 45 
Turbo Debugger, 657, 683 
TWOFILE.H header file, 178 
TWO Fl LE.M AK MAKE file 

advanced version, 184-186 

simple version, 183 
TWOFILE1.C program, 171-175 
TWO Fl LE2.C program, 176-178 
typecasting, 41-42 
type parameter, 598 
typedef keyword, 10, 208 
typedef statement, 167 
TYPEDEF. H header file, 168-169, 180 

U 



u field, 612, 617 

UART (Universal Asynchronous 

Receiver/Transmitter), 296 
UCH AR_M AX identifier, 21, 508 
UINT_MAX identifier, 22, 509 
U LO N G_M AX identifier, 22, 509 
#undef directive, 637 
UnderFlowO function, 395, 427 
ungetcO function, 270, 597 
ungetch() function, 281 
union keyword, 10 
UNION.C program, 220-225 
unions, 219-220, 225 
unititialized variables, 643 
U niversal Asynchronous Receiver/ 

Transmitter (UART), 296 
unlink() function, 267 
unsigned int constants, 26 
unsigned keyword, 10 
unsigned modifier, 20 
updating dBASE files, 494 



_UPPER identifier, 502 

user interfaces, 162 

USH RT_M AX identifier, 22, 509 

utilities 

DEBUG, 146 

DOSSORT,322 

LIB, 182 

WDISASM, 437-438 
V 



va_ function, 600 
va_arg() function, 598 
va_start() function, 601 
values 

default parameter, 706 

E2BIG, 504 

EACCES, 504 

EAGAIN, 505 

EBADF, 505 

EDEADLOCK, 505 

EDO M , 505 

EEXIST, 505 

EINVAL, 505 

EM FILE, 505 

ENOENT, 505 

ENOEXEC, 505 

ENOMEM,505 

ENOSPC, 505 

ERANGE, 505 

EXDEV, 505 

return, 498 

SIGABRT, 512 

SIGBREAK, 512 

SIGFPE, 512 

SIGILL, 512 

SIGINT, 512 
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SIGSEGV, 512 

SIGTERM, 512 
VarArgs parameter, 601-604 
varargsh header file, 518 
VARGS.C program, 513-515 
variables, 35 

automatic, 644 

bDay, 471 

bfHasMemo, 470 

bf VERSION, 470 

bM onth, 471 

bYear, 470 

declaring, 704 

external, 40, 171 

global, 644 

initializing, 15, 35-36 

integer, defining, 30 

lifespan, 39 

IN umberRecords, 471 

nColumnCount, 483 

nCurrentParameter, 112 

nFirstRecordOffset, 471 

nLineWidth, 113 

n Record Length, 471 

reference 
as return values, 711 
in C++, 710 

scope, 37 

scratch, 644 

shared, 164 

size, 465 

state, 135 

static, declaring, 30 
temporary, 663 
type, 465 

typecasting, 41-42 



types, 35-36 

unititialized, 643 
VARS.H header file, 169-170, 180 
version codes, 470 
vfprintf() function, 271, 601 
VIDEO debugger, 657 
video I/O, direct, 667 
void keyword, 10 
volatile identifier, 7, 500 
vprintf() function, 271-272, 602 
vsprintf() function, 271, 604 



W 



Watcom C/386 compiler, 438, 659, 
692-694 

WCHBYTE.C program, 152-153 
western bs() function, 605 
wctombO function, 606 
WDISASM utility, 437-438 
while keyword, 10 
whitespace characters, 550 
W ideC har parameter, 606 
width parameter, 527 
width specifier, 112 
W indows N T operating system, 659 
work files, temporary, 256, 267-268 
Workshop program, 682 
write() function, 279 
writing code in multiple languages, 
435-436 
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xand X fields, 613-616 
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